@xemahq/kernel-contracts 0.1.0 → 0.2.1

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

@@ -0,0 +1,109 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker runtime — driver contract ──
+//
+// The minimal interface every worker-runtime implementation satisfies. The
+// kernel does NOT know about Kubernetes pod specs — `BuildPodSpecInput` is
+// deliberately schedule-agnostic. Concrete schedulers (k8s, docker-swarm,
+// docker-local) live in the platform/runtime services and translate this
+// abstract spec to their native shapes.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { AbstractMount } from '../../workspace-storage';
+
+import type {
+  SchedulerCapabilityRequest,
+  WorkerRuntimeCapabilityBits,
+} from './capabilities';
+import type { WorkerRuntimeKind } from './enums';
+import type { RuntimeEvent, UserMessage } from './messages';
+
+/**
+ * Schedule-agnostic input the composer hands to `buildPodSpec`. Concrete
+ * scheduler adapters translate this to their native shape (k8s `PodSpec`,
+ * Docker `ContainerCreateOptions`, …). Intentionally minimal — adding a
+ * k8s-specific field here would leak scheduler knowledge into the kernel.
+ */
+export interface BuildPodSpecInput {
+  /** Image reference (registry/name:tag or digest). */
+  readonly image: string;
+  /** Env vars to set on the worker process. */
+  readonly env: Readonly<Record<string, string>>;
+  /** Volume mounts produced by storage drivers (`/workspace`, `/templates`). */
+  readonly mounts: readonly AbstractMount[];
+  /** Optional region hint for co-scheduling with storage pools. */
+  readonly region?: string;
+  /** Scheduler features the runtime depends on. */
+  readonly capabilities: readonly SchedulerCapabilityRequest[];
+}
+
+/**
+ * Input describing the agent + skills + model configuration to bundle for
+ * a worker. `mcpConfig` and `opencodeConfigBase64` are intentionally typed
+ * as opaque strings at the kernel level — runtime implementations
+ * interpret them. Other runtimes may carry a runtime-specific blob in the
+ * same `opencodeConfigBase64` slot under a different conceptual name once
+ * the kernel generalizes that field.
+ */
+export interface BuildBundleInput {
+  /** Slug of the primary agent that owns the turn. */
+  readonly primaryAgent: string;
+  /** Slugs of sub-agents the primary may delegate to. */
+  readonly subAgents: readonly string[];
+  /** Per-invocation model override; absent = matrix-resolved default. */
+  readonly modelOverride?: string;
+  /** Opaque MCP config blob; runtime-specific. */
+  readonly mcpConfig?: string;
+  /** Opaque base64-encoded OpenCode config; runtime-specific. */
+  readonly opencodeConfigBase64?: string;
+}
+
+/**
+ * A session bundle is an opaque wrapper passed to `applySessionBundle`.
+ * The `fingerprint` is a stable content hash callers use to short-circuit
+ * re-application; the `payloadBase64` is interpreted only by the runtime
+ * implementation that produced it.
+ */
+export interface SessionBundle {
+  readonly fingerprint: string;
+  readonly payloadBase64: string;
+}
+
+/**
+ * The contract every worker-runtime implementation MUST satisfy. The
+ * implementation lives in the appropriate platform/runtime SDK
+ * (e.g. opencode-runtime-driver).
+ */
+export interface WorkerRuntime {
+  readonly kind: WorkerRuntimeKind;
+  readonly capabilities: WorkerRuntimeCapabilityBits;
+  /**
+   * The connector kind (from `@xemahq/connector-contracts`) this runtime
+   * must be paired with at session-start. The composer fails fast if a
+   * runtime is invoked without a connector of this kind in scope.
+   */
+  readonly connectorKindRequired: string;
+
+  /** Build the schedule-agnostic pod spec for a worker. */
+  buildPodSpec(input: BuildPodSpecInput): Promise<unknown>;
+
+  /** Compose a session bundle from the agent/skills/model inputs. */
+  buildSessionBundle(input: BuildBundleInput): Promise<SessionBundle>;
+
+  /** Push a previously-built bundle into a live worker (idempotent). */
+  applySessionBundle(bundle: SessionBundle): Promise<void>;
+
+  /** Send a user message; runtime streams events back. */
+  sendUserMessage(message: UserMessage): AsyncIterable<RuntimeEvent>;
+
+  /** Pause a session — the worker may be scaled to zero. */
+  pause(): Promise<void>;
+
+  /** Resume a previously-paused session — worker comes back online. */
+  resume(): Promise<void>;
+
+  /**
+   * True iff this runtime supports a `tool.execute.after` hook that
+   * auto-commits workspace changes (used by the workflow surface).
+   */
+  readonly autoCommitHookSupported: boolean;
+}

package/src/worker-runtime/lib/schemas.ts

@@ -0,0 +1,72 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Worker runtime — zod schemas ──
+//
+// Runtime validators for value-typed shapes that may cross the wire:
+// enums, capability bits, actor/attachment/message, runtime events. We do
+// NOT validate the `WorkerRuntime` interface itself (it's an in-process
+// object with non-serializable methods).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { HookKind, WorkerRuntimeKind } from './enums';
+
+export const workerRuntimeKindSchema = z.nativeEnum(WorkerRuntimeKind);
+export const hookKindSchema = z.nativeEnum(HookKind);
+
+export const workerRuntimeCapabilityBitsSchema = z.object({
+  hotMcp: z.boolean(),
+  hotModelSwap: z.boolean(),
+  sessionFork: z.boolean(),
+  subAgentCrud: z.boolean(),
+  hooks: z.array(hookKindSchema).readonly(),
+  previewSupervisor: z.boolean(),
+  gatewayAttributedCalls: z.boolean(),
+  llmEndpointOverride: z.boolean(),
+});
+
+export const schedulerCapabilityBitsSchema = z.object({
+  autoRestart: z.boolean(),
+  healthCheck: z.boolean(),
+  hpa: z.boolean(),
+  networkPolicy: z.boolean(),
+});
+
+export const schedulerCapabilityRequestSchema = z.object({
+  kind: z.enum(['autoRestart', 'healthCheck', 'hpa', 'networkPolicy']),
+  optional: z.boolean(),
+});
+
+export const actorRefSchema = z.object({
+  subjectKind: z.enum(['org_user', 'external_guest']),
+  subjectRef: z.string().min(1),
+  displayName: z.string().min(1),
+});
+
+export const attachmentSchema = z.object({
+  kind: z.enum(['file', 'image', 'url']),
+  value: z.string().min(1),
+});
+
+export const userMessageSchema = z.object({
+  actor: actorRefSchema,
+  content: z.string(),
+  attachments: z.array(attachmentSchema).optional(),
+});
+
+export const runtimeEventSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('text-delta'), text: z.string() }),
+  z.object({ kind: z.literal('tool-use'), tool: z.string().min(1), input: z.unknown() }),
+  z.object({ kind: z.literal('tool-result'), tool: z.string().min(1), output: z.unknown() }),
+  z.object({ kind: z.literal('turn-end') }),
+  z.object({
+    kind: z.literal('error'),
+    message: z.string(),
+    retryable: z.boolean(),
+  }),
+]);
+
+export const sessionBundleSchema = z.object({
+  fingerprint: z.string().min(1),
+  payloadBase64: z.string().min(1),
+});

package/src/workflow/lib/activity-outputs.ts

@@ -91,7 +91,7 @@ export interface ActivityOutputDeclaration {
 
 // NOTE: per-output deliverable-spec bindings live on the action
 // MANIFEST (`spec.outputBindings`, see `ActionManifestSpec` in
-// `@xemahq/workflow-dsl`) — that's the single source of truth the DSL
+// `@xemahq/dsl/workflow`) — that's the single source of truth the DSL
 // compiler reads at compile time. `OUTPUT_DECLARATIONS` is a worker-
 // internal contract used by the output-promotion wrapper, so binding
 // metadata never has to flow through it.

package/src/workflow/lib/compiled-run.ts

@@ -38,7 +38,7 @@ export type CompiledManifestSource =
 
 /**
  * A CompiledRun is the IMMUTABLE semantic expansion of a workflow definition
- * for one execution. Produced by `@xemahq/workflow-dsl` at run
+ * for one execution. Produced by `@xemahq/dsl/workflow` at run
  * start, written to the snapshot store, referenced by {@link SnapshotRef}
  * as the input to `rootRunWorkflow`.
  *

package/src/workflow/lib/compiled-workspace-manifest.ts

@@ -1,6 +1,6 @@
 /**
  * Compiled output types for WorkspaceManifest — produced by
- * `@xemahq/workspace-manifest-dsl`'s `compileManifest()` and embedded
+ * `@xemahq/dsl/workspace-manifest`'s `compileManifest()` and embedded
  * in {@link CompiledRun} for inline-agent steps.
  *
  * Defined here (rather than in workspace-manifest-dsl) to avoid a

package/src/workflow/lib/model-ref.ts

@@ -30,7 +30,7 @@ import { z } from 'zod';
  *
  * Mirrors `biomes/agent-runtime/api/llm-registry-api`'s Prisma `ModelClass` column.
  *
- * IMPORTANT — the one allowed copy is in `@xemahq/biome-builder`'s
+ * IMPORTANT — the one allowed copy is in `@xemahq/biome-sdk/builder`'s
  * `contribution-schemas.ts`, because that package publishes to the
  * public npm registry and cannot depend on this GitHub-Packages-scoped
  * package. That copy carries a comment marker; keep both lists

package/src/workflow/lib/workspace-manifest-enums.ts

@@ -1,7 +1,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 // ── Workspace Manifest closed-domain enums ──
 //
-// Kernel-tier closed sets consumed by `@xemahq/workspace-manifest-dsl`,
+// Kernel-tier closed sets consumed by `@xemahq/dsl/workspace-manifest`,
 // `@xemahq/agent-session-runtime`, the workflow DSL compiler, the
 // llm-registry-api composition seeder, and frontend manifest editors.
 // Each enum keeps the manifest contract auditable end-to-end —

package/src/workspace-storage/index.ts

@@ -0,0 +1,12 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace Storage Contracts — Barrel Export ──
+//
+// Kernel (Layer 1) contracts for the storage-pool / allocator abstraction.
+// Pure types + closed enums + zod schemas. Zero NestJS, zero Prisma,
+// zero platform assumptions (no k8s, no docker-specifics). Concrete
+// driver implementations live in the storage-pool service.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/enums';
+export * from './lib/types';
+export * from './lib/schemas';

package/src/workspace-storage/lib/enums.ts

@@ -0,0 +1,78 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace storage — closed-domain enums ──
+//
+// Kernel-level enums shared across every consumer of the StorageDriver
+// abstraction: the storage-pool service, workspace allocator, and worker
+// runtime. NO platform-specific assumptions live here — every enum value
+// describes a generic concept.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The role an attachment plays inside a worker pod. Storage drivers may
+ * mount the same underlying pool for either purpose; the kind dictates the
+ * mount path convention used by the workspace composer.
+ */
+export enum AttachmentKind {
+  /** Read-write per-session workspace (`/workspace`). */
+  Workspace = 'workspace',
+  /** Read-only template share (`/templates`). */
+  Templates = 'templates',
+}
+
+/**
+ * Closed set of storage backends Xema knows how to drive. New backends MUST
+ * be added here AND implement the `StorageDriver` interface; consumers MUST
+ * `switch` exhaustively.
+ */
+export enum StorageDriverKind {
+  Longhorn = 'longhorn',
+  EFS = 'efs',
+  Filestore = 'filestore',
+  AzureFiles = 'azure_files',
+  DockerLocal = 'docker_local',
+  DockerSwarmCsi = 'docker_swarm_csi',
+  Nfs = 'nfs',
+  HostPath = 'host_path',
+}
+
+/**
+ * Lifecycle of a managed storage pool. Pools progress provisioning → active
+ * → draining → decommissioned. A pool in any non-`active` state must refuse
+ * new allocations.
+ */
+export enum PoolStatus {
+  Provisioning = 'provisioning',
+  Active = 'active',
+  Draining = 'draining',
+  Decommissioned = 'decommissioned',
+}
+
+/**
+ * Who an allocation belongs to.
+ *
+ * The `template_*` scopes are read-only template shares mounted under
+ * `/templates` (the system tier is platform-shipped; the org tier is
+ * tenant-curated). They are distinct from the per-session/project/org
+ * workspace scopes so the allocator can route them to different driver
+ * configs (e.g. a read-only PV vs a read-write PVC).
+ */
+export enum AllocationScope {
+  Org = 'org',
+  Project = 'project',
+  Session = 'session',
+  TemplateOrg = 'template_org',
+  TemplateSystem = 'template_system',
+}
+
+/**
+ * Lifecycle of a single storage allocation. `pending` allocations have no
+ * mounted volume yet; `ready` means the sub-path exists and can be mounted.
+ * `archived` keeps the sub-path on the pool but disallows new mounts;
+ * `deleted` removes the sub-path entirely.
+ */
+export enum AllocationStatus {
+  Pending = 'pending',
+  Ready = 'ready',
+  Archived = 'archived',
+  Deleted = 'deleted',
+}

package/src/workspace-storage/lib/schemas.ts

@@ -0,0 +1,75 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace storage — zod schemas ──
+//
+// Runtime validators mirroring the enums and DTOs in this package. Kept in
+// a separate file so type-only consumers can tree-shake them out.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import {
+  AllocationScope,
+  AllocationStatus,
+  AttachmentKind,
+  PoolStatus,
+  StorageDriverKind,
+} from './enums';
+
+export const attachmentKindSchema = z.nativeEnum(AttachmentKind);
+export const storageDriverKindSchema = z.nativeEnum(StorageDriverKind);
+export const poolStatusSchema = z.nativeEnum(PoolStatus);
+export const allocationScopeSchema = z.nativeEnum(AllocationScope);
+export const allocationStatusSchema = z.nativeEnum(AllocationStatus);
+
+export const abstractMountSchema = z.object({
+  poolId: z.string().min(1),
+  subPath: z.string().min(1),
+  mountPath: z.string().min(1),
+  readOnly: z.boolean().optional(),
+  driverHandle: z.string().min(1),
+});
+
+export const poolSpecSchema = z.object({
+  slug: z.string().min(1),
+  driverKind: storageDriverKindSchema,
+  driverConfig: z.record(z.string(), z.unknown()),
+  capacityBytes: z.bigint().nonnegative(),
+  region: z.string().min(1),
+  environment: z.string().min(1).optional(),
+  costClass: z.string().min(1).optional(),
+});
+
+export const ensuredPoolSchema = z.object({
+  poolId: z.string().min(1),
+  pvcName: z.string().min(1),
+  pvcNamespace: z.string().min(1),
+  status: poolStatusSchema,
+});
+
+export const storagePoolSchema = z.object({
+  id: z.string().min(1),
+  slug: z.string().min(1),
+  driverKind: storageDriverKindSchema,
+  region: z.string().min(1),
+  environment: z.string().min(1).optional(),
+  capacityBytes: z.bigint().nonnegative(),
+  costClass: z.string().min(1).optional(),
+  status: poolStatusSchema,
+  createdAt: z.string().min(1),
+  updatedAt: z.string().min(1),
+});
+
+export const storageAllocationSchema = z.object({
+  id: z.string().min(1),
+  poolId: z.string().min(1),
+  scope: allocationScopeSchema,
+  orgId: z.string().min(1).optional(),
+  projectId: z.string().min(1).optional(),
+  sessionId: z.string().min(1).optional(),
+  region: z.string().min(1),
+  subPath: z.string().min(1),
+  bytesUsed: z.bigint().nonnegative(),
+  status: allocationStatusSchema,
+  lastTouchedAt: z.string().min(1),
+  createdAt: z.string().min(1),
+});

package/src/workspace-storage/lib/types.ts

@@ -0,0 +1,145 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Workspace storage — driver & mount types ──
+//
+// Abstract types every storage driver implementation must satisfy. The
+// kernel is platform-agnostic: nothing here knows about Kubernetes, Docker
+// Swarm, or any specific filesystem — those concerns live in concrete
+// driver implementations under apps/<storage-pool-api>/drivers/*.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type {
+  AllocationScope,
+  AllocationStatus,
+  AttachmentKind,
+  PoolStatus,
+  StorageDriverKind,
+} from './enums';
+
+/**
+ * A mount the worker-runtime composer will attach to a pod. The
+ * `driverHandle` is an opaque token whose meaning is interpreted by the
+ * storage driver that produced it (e.g. a PVC name for k8s, a host path
+ * for docker-local). Consumers MUST NOT parse it.
+ */
+export interface AbstractMount {
+  /** Storage pool that backs this mount. */
+  readonly poolId: string;
+  /** Sub-path inside the pool (e.g. `org/<id>/project/<id>/session/<id>`). */
+  readonly subPath: string;
+  /** Path inside the worker container (e.g. `/workspace`, `/templates`). */
+  readonly mountPath: string;
+  /** Defaults to false (read-write). Template mounts are typically true. */
+  readonly readOnly?: boolean;
+  /** Opaque driver-defined handle; never inspected by callers. */
+  readonly driverHandle: string;
+}
+
+/**
+ * Desired-state input for `ensurePool`. The driver MUST be idempotent on
+ * `slug`: re-calling with the same slug returns the same pool.
+ */
+export interface PoolSpec {
+  readonly slug: string;
+  readonly driverKind: StorageDriverKind;
+  /**
+   * Driver-specific config. The driver implementation validates its own
+   * shape; the kernel only guarantees it is a JSON-serializable object.
+   */
+  readonly driverConfig: Record<string, unknown>;
+  readonly capacityBytes: bigint;
+  /** Required for region-aware co-scheduling (see plan §15). */
+  readonly region: string;
+  readonly environment?: string;
+  /** Free-form cost class label for billing/observability dashboards. */
+  readonly costClass?: string;
+}
+
+/**
+ * Output of `ensurePool`. The pvc fields are populated for backends that
+ * project pools as Kubernetes PVCs; other drivers may return synthetic
+ * names — they remain opaque to callers.
+ */
+export interface EnsuredPool {
+  readonly poolId: string;
+  readonly pvcName: string;
+  readonly pvcNamespace: string;
+  readonly status: PoolStatus;
+}
+
+/**
+ * Storage driver interface — implemented by one concrete driver per
+ * `StorageDriverKind`. Methods are idempotent and safe to call from
+ * multiple coordinator replicas (the driver is responsible for advisory
+ * locking around physical operations).
+ */
+export interface StorageDriver {
+  readonly kind: StorageDriverKind;
+
+  /** Create or update a pool to match `spec`. Idempotent on `spec.slug`. */
+  ensurePool(spec: PoolSpec): Promise<EnsuredPool>;
+
+  /** Mark a pool as draining; refuse new allocations; await zero mounts. */
+  drainPool(poolId: string): Promise<void>;
+
+  /** Ensure a sub-path exists inside a pool. Idempotent. */
+  ensureSubPath(input: {
+    readonly poolId: string;
+    readonly subPath: string;
+    readonly scope: AllocationScope;
+  }): Promise<void>;
+
+  /** Remove a sub-path. Idempotent — absent path is a no-op. */
+  deleteSubPath(input: {
+    readonly poolId: string;
+    readonly subPath: string;
+  }): Promise<void>;
+
+  /**
+   * Build the AbstractMount that a worker-runtime composer can hand to its
+   * scheduler. Pure description — no side effects, no I/O.
+   */
+  describeAttachment(input: {
+    readonly poolId: string;
+    readonly subPath: string;
+    readonly mountPath: string;
+    readonly kind: AttachmentKind;
+    readonly readOnly?: boolean;
+  }): AbstractMount;
+}
+
+/**
+ * Cross-service DTO for a managed pool. Mirrors the Prisma row shape in
+ * the storage-pool service so callers (worker-runtime, allocator,
+ * frontend) can share one type.
+ */
+export interface StoragePool {
+  readonly id: string;
+  readonly slug: string;
+  readonly driverKind: StorageDriverKind;
+  readonly region: string;
+  readonly environment?: string;
+  readonly capacityBytes: bigint;
+  readonly costClass?: string;
+  readonly status: PoolStatus;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+/**
+ * Cross-service DTO for a single allocation. `bytesUsed` is a best-effort
+ * snapshot — callers must not gate hard limits on this value alone.
+ */
+export interface StorageAllocation {
+  readonly id: string;
+  readonly poolId: string;
+  readonly scope: AllocationScope;
+  readonly orgId?: string;
+  readonly projectId?: string;
+  readonly sessionId?: string;
+  readonly region: string;
+  readonly subPath: string;
+  readonly bytesUsed: bigint;
+  readonly status: AllocationStatus;
+  readonly lastTouchedAt: string;
+  readonly createdAt: string;
+}