@xemahq/kernel-contracts 0.1.0

package/src/runner/lib/dispatch.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import {
+  ExecutionContextSchema,
+  type ExecutionContext,
+} from '../../execution-context';
+
+/**
+ * CloudEvent type emitted on the dispatch fan-out channel (Phase F.3
+ * Push transport). Pull-mode runners receive the same envelope as the
+ * body of `POST /runners/<id>/pull-work`.
+ *
+ * Constant, not enum — there is exactly one dispatch type today.
+ * If the wire format ever forks (e.g. a streaming variant), bump the
+ * `.v1` suffix and add the new constant alongside.
+ */
+export const RUNNER_DISPATCH_CLOUDEVENT_TYPE = 'xema.runner.dispatch.v1' as const;
+
+/**
+ * `RunnerDispatch` (Phase F.3) — superset of the legacy
+ * `RunnerJobDispatch` shape. This v1 envelope carries the full
+ * `ExecutionContext` so the runner can re-validate the policy decision
+ * locally before invoking the capability.
+ *
+ * `tokenJwt` is the compact-JWS form of the RS256 `JobToken` minted by
+ * the kernel-server (Phase F.5), aligned with `RunnerJobDispatch.tokenJwt`.
+ * The runner MUST verify the signature + claims against the kernel-server
+ * JWKS before touching the dispatch.
+ */
+export interface RunnerDispatch {
+  jobId: string;
+  runnerInstanceId: string;
+  capabilityRef: string;
+  executionContext: ExecutionContext;
+  /**
+   * The capability invocation input, carried by value so the runner has the
+   * actual arguments to execute with (Phase F.7). The `ExecutionContext`
+   * carries only an `inputHash` fingerprint — not the payload — so without
+   * this field the runner could verify identity but had nothing to run.
+   *
+   * Integrity: the kernel-server binds `canonicalCapabilityInputHash(input)`
+   * into the `JobToken` as the `ih` claim; the runner recomputes the hash
+   * from THIS field and refuses the dispatch if it does not match the signed
+   * claim. The input therefore travels unsigned but tamper-evident.
+   */
+  input: unknown;
+  /**
+   * Compact-JWS encoding of the signed `JobToken` minted by the
+   * kernel-server. The runner decodes + verifies this against the
+   * published JWKS before invoking the capability.
+   */
+  tokenJwt: string;
+}
+
+export const RunnerDispatchSchema = z.object({
+  jobId: z.string().min(1),
+  runnerInstanceId: z.string().min(1),
+  capabilityRef: z.string().min(1),
+  executionContext: ExecutionContextSchema,
+  input: z.unknown(),
+  tokenJwt: z.string(),
+}) as z.ZodType<RunnerDispatch>;

package/src/runner/lib/input-hash.ts

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Deterministic canonical hash of a capability invocation input (plan §6
+ * Phase F.7, input-integrity binding).
+ *
+ * The runner plane separates execution authority: the kernel-server mints
+ * the RS256 `JobToken` and the router dispatches the `RunnerDispatch`. Under
+ * PUSH at-least-once fan-out the dispatch envelope is broadcast, so the
+ * `input` payload travels OUTSIDE the signed token. To keep the input
+ * tamper-evident, the kernel-server binds `sha256(canonical(input))` into the
+ * token as the `ih` claim and the runner recomputes + compares it against the
+ * `input` it received before invoking. A mismatch means the input was altered
+ * in transit (or a token was paired with a different input) — the runner
+ * refuses the dispatch fail-fast.
+ *
+ * The hash MUST be computed identically by the producer (router gateway) and
+ * the verifier (runner), so the canonicalisation is fully deterministic:
+ *   - object keys are sorted lexicographically, recursively;
+ *   - `undefined`-valued object properties are dropped (they are absent on
+ *     the wire after JSON serialisation anyway);
+ *   - a top-level `undefined` input is normalised to the empty object `{}`
+ *     so a no-input capability and an explicit `{}` hash identically;
+ *   - arrays preserve order;
+ *   - non-JSON values (`bigint`, `function`, `symbol`, non-finite numbers)
+ *     are rejected — capability input is JSON, never a host object.
+ */
+export function canonicalCapabilityInputHash(input: unknown): string {
+  const canonical = canonicalize(input === undefined ? {} : input);
+  return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) {
+    // A nested `undefined` only reaches here via an array hole; treat it as
+    // `null` to match JSON.stringify's array behaviour.
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(',')}]`;
+  }
+  const valueType = typeof value;
+  if (valueType === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        'canonicalCapabilityInputHash: non-finite number is not valid JSON capability input.',
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (valueType === 'boolean' || valueType === 'string') {
+    return JSON.stringify(value);
+  }
+  if (valueType === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj)
+      .filter((key) => obj[key] !== undefined)
+      .sort();
+    return `{${keys
+      .map((key) => `${JSON.stringify(key)}:${canonicalize(obj[key])}`)
+      .join(',')}}`;
+  }
+  throw new Error(
+    `canonicalCapabilityInputHash: unsupported value type "${valueType}" in capability input.`,
+  );
+}

package/src/runner/lib/job-token.ts

@@ -0,0 +1,80 @@
+import type { RunnerId } from './runner';
+
+/**
+ * Signed job token (plan §6 Phase F.5).
+ *
+ * Kernel-server mints an RS256 token with a hard ceiling of 60 seconds
+ * per invocation. The runner MUST verify signature + scope before
+ * executing the dispatch and MUST refuse a token whose claims do not
+ * match the accompanying `RunnerJobDispatch`. Replay (same `jti`) MUST
+ * be rejected by the runner's local de-dup ring.
+ *
+ * The token is carried in `RunnerJobDispatch.tokenJwt` as the on-wire
+ * JWS form; this interface is its decoded shape.
+ */
+export interface JobToken {
+  /**
+   * Unique token identifier. Runner de-dup is keyed on this value.
+   */
+  jti: string;
+  runnerId: RunnerId;
+  /**
+   * Capability ref this token authorizes (must match
+   * `RunnerJobDispatch.capabilityRef` exactly).
+   */
+  capabilityRef: string;
+  /**
+   * Space the invocation runs in (org / project / app SpaceRef
+   * canonical form). Carried as a string so this leaf does not depend
+   * on `@xemahq/execution-environment-contracts`.
+   */
+  spaceRef: string;
+  environmentId: string;
+  /**
+   * Authenticated subject (user / agent / app / service / runner /
+   * external-subject) under which the capability is invoked.
+   */
+  subjectId: string;
+  /**
+   * `canonicalCapabilityInputHash` of the dispatched invocation input
+   * (Phase F.7). Binds the unsigned `RunnerDispatch.input` to this signed
+   * token so the runner can detect input tampering before executing.
+   */
+  inputHash: string;
+  /**
+   * Absolute UTC ISO-8601 timestamps. The kernel-server caps
+   * `expiresAt - issuedAt <= 60s`.
+   */
+  issuedAt: string;
+  expiresAt: string;
+  /**
+   * Detached RS256 signature in compact-JWS form. Implementations MUST
+   * NOT trust the payload until the signature verifies against the
+   * kernel-server's published JWKS.
+   */
+  signature: string;
+}
+
+/**
+ * Envelope handed to the runner. Pull-mode runners receive this as the
+ * response body of `POST /runners/<id>/pull-work`; Push-mode runners
+ * receive this as the payload of the `xema.runner.dispatch.v1`
+ * CloudEvent.
+ */
+export interface RunnerJobDispatch {
+  jobId: string;
+  runnerId: RunnerId;
+  capabilityRef: string;
+  /**
+   * Opaque execution-context handle the runner echoes back on every
+   * progress / completion event. Carried as a string for the same
+   * reason as `JobToken.spaceRef`.
+   */
+  contextId: string;
+  input: unknown;
+  /**
+   * Compact-JWS encoding of the corresponding `JobToken`. The runner
+   * decodes + verifies this before touching `input`.
+   */
+  tokenJwt: string;
+}

package/src/runner/lib/runner-attestation.ts

@@ -0,0 +1,53 @@
+import type { RunnerId } from './runner';
+
+/**
+ * CloudEvent type the kernel-server emits when it REJECTS a runner
+ * attestation (bad SA-JWT, stale `signedAt`, un-countersigned
+ * `allowedEnvironments`, …). Fail-fast — the runner is refused.
+ *
+ * Constant, not enum — exactly one rejected type today (same convention
+ * as `RUNNER_DISPATCH_CLOUDEVENT_TYPE`).
+ */
+export const RUNNER_ATTESTATION_REJECTED_CLOUDEVENT_TYPE =
+  'xema.runner.attestation.rejected.v1' as const;
+
+/**
+ * Runner attestation (plan §6 Phase F.4).
+ *
+ * Carried by a runner on every `register` against the kernel-server.
+ * The kernel-server validates:
+ * - `identityJwt` is signed by the trusted Keycloak realm and the
+ *   subject is a service-account claim of kind `runner`.
+ * - `allowedEnvironments` is countersigned by an org-admin role
+ *   (validated via OpenFGA / OPA — see Phase D).
+ * - `signedAt` is within the configured attestation freshness window.
+ *
+ * Any validation failure is fail-fast — the runner is rejected and the
+ * kernel-server emits a `runner.attestation.rejected.v1` CloudEvent.
+ */
+export interface RunnerAttestation {
+  runnerId: RunnerId;
+  /**
+   * UTC ISO-8601 timestamp at which the attestation envelope was
+   * signed. The kernel-server REJECTS attestations older than the
+   * configured freshness window (default 5 minutes).
+   */
+  signedAt: string;
+  /**
+   * Keycloak service-account JWT proving the runner's identity. The
+   * kernel-server verifies the signature against the realm's JWKS and
+   * extracts the subject claim.
+   */
+  identityJwt: string;
+  /**
+   * IDs of `ExecutionEnvironment`s this runner is permitted to serve.
+   * Countersigned by an org-admin role; the kernel-server refuses a
+   * runner that claims an environment outside its admin's authority.
+   */
+  allowedEnvironments: string[];
+  /**
+   * Optional data-residency labels (e.g. `eu-west`, `customer-private`)
+   * consumed by `Policy.routeHints` for region-aware dispatch.
+   */
+  dataResidencyLabels?: string[];
+}

package/src/runner/lib/runner-job.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+
+/**
+ * `RunnerJob` lifecycle state machine (plan §6 Phase F.7).
+ *
+ *   Pending → Dispatched → Accepted → Running → Succeeded (terminal)
+ *                                            ↘ Failed     (terminal)
+ *   (any non-terminal state) ──────────────→ Expired      (terminal)
+ *
+ * Owned by `workload-runtime-api`, which mirrors the `WorkloadState`
+ * shape: a closed enum plus an `isTerminalRunnerJobState()` helper.
+ * Terminal states never transition again — the state machine refuses any
+ * outbound edge from them (fail-fast).
+ *
+ * Closed set; adding a state is a coordinated kernel change.
+ */
+export enum RunnerJobState {
+  Pending = 'pending',
+  Dispatched = 'dispatched',
+  Accepted = 'accepted',
+  Running = 'running',
+  Succeeded = 'succeeded',
+  Failed = 'failed',
+  Expired = 'expired',
+}
+
+export const RunnerJobStateSchema = z.nativeEnum(RunnerJobState);
+
+export const TERMINAL_RUNNER_JOB_STATES: ReadonlySet<RunnerJobState> = new Set([
+  RunnerJobState.Succeeded,
+  RunnerJobState.Failed,
+  RunnerJobState.Expired,
+]);
+
+export function isTerminalRunnerJobState(state: RunnerJobState): boolean {
+  return TERMINAL_RUNNER_JOB_STATES.has(state);
+}
+
+/**
+ * CloudEvent type emitted by a runner when it ACCEPTS a dispatched job
+ * (transition `Dispatched → Accepted`). `workload-runtime` consumes it to
+ * advance the `RunnerJob` row.
+ *
+ * Constant, not enum — exactly one accepted type today. If the wire
+ * format forks, bump the `.v1` suffix and add the new constant alongside
+ * (same convention as `RUNNER_DISPATCH_CLOUDEVENT_TYPE`).
+ */
+export const RUNNER_JOB_ACCEPTED_CLOUDEVENT_TYPE =
+  'xema.runner.job.accepted.v1' as const;
+
+/**
+ * CloudEvent type emitted by a runner for incremental progress on a
+ * running job (`Accepted → Running`, and subsequent heartbeats).
+ */
+export const RUNNER_JOB_PROGRESS_CLOUDEVENT_TYPE =
+  'xema.runner.job.progress.v1' as const;
+
+/**
+ * CloudEvent type emitted by a runner when a job reaches a terminal
+ * outcome (`Running → Succeeded | Failed`). Carries the `RunnerJobReport`.
+ */
+export const RUNNER_JOB_COMPLETED_CLOUDEVENT_TYPE =
+  'xema.runner.job.completed.v1' as const;
+
+/**
+ * Report-back envelope a runner emits on accept / progress / completion
+ * (Phase F.7). `workload-runtime` keys idempotent state transitions on
+ * `(jobId, state)`; `output` is present only on a `Succeeded` report and
+ * `error` only on a `Failed` report.
+ */
+export interface RunnerJobReport {
+  jobId: string;
+  runnerId: string;
+  state: RunnerJobState;
+  /** Capability output, present on a `Succeeded` report. */
+  output?: unknown;
+  /** Failure detail, present on a `Failed` report. */
+  error?: string;
+  /** UTC ISO-8601 timestamp at which the runner emitted the report. */
+  reportedAt: string;
+}
+
+export const RunnerJobReportSchema = z.object({
+  jobId: z.string().min(1),
+  runnerId: z.string().min(1),
+  state: RunnerJobStateSchema,
+  output: z.unknown().optional(),
+  error: z.string().optional(),
+  reportedAt: z.string().min(1),
+}) as z.ZodType<RunnerJobReport>;

package/src/runner/lib/runner-kind.ts

@@ -0,0 +1,10 @@
+/**
+ * Re-export `RunnerKind` + its Zod schema from `@xemahq/policy-contracts`.
+ *
+ * The closed enum lives in `policy-contracts` because the policy
+ * decision layer is its primary author (`PolicyObligation.RequireRunnerKind`
+ * and `RouteHint.preferredRunnerKind` both reference it). Runner-side
+ * code imports it from here so consumers don't have to remember which
+ * leaf owns the canonical declaration.
+ */
+export { RunnerKind, RunnerKindSchema } from '../../policy';

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

@@ -0,0 +1,16 @@
+/**
+ * Runner transport mode (plan §6 Phase F.3).
+ *
+ * - `Push` (cluster default) — kernel-server emits
+ *   `xema.runner.dispatch.v1` CloudEvent; runner consumes via
+ *   event-hub subscription.
+ * - `Pull` (customer-edge default) — runner long-polls
+ *   `POST /runners/<id>/pull-work`; works through NAT.
+ *
+ * Closed set. Adding a third transport (e.g. WebSocket) is a kernel
+ * change, not a runner config change.
+ */
+export enum RunnerTransportMode {
+  Push = 'push',
+  Pull = 'pull',
+}

package/src/runner/lib/runner-plane.ts

@@ -0,0 +1,101 @@
+/**
+ * Runner-plane registry conventions (plan §6 Phase F.6).
+ *
+ * Runners do not have a bespoke registry; they publish ordinary
+ * `ServiceDescriptor`s to the Service Registry under ONE well-known
+ * name (`RUNNER_PLANE_SERVICE_NAME`) and carry their runner-classifying
+ * fields (kind, mode, transport, data-locality, region) as descriptor
+ * `labels`. The capability router resolves every instance registered
+ * under that name and maps each descriptor to a `RunnerRegistration`
+ * via `runnerRegistrationFromDescriptor` (defined in the router, where
+ * the `ServiceDescriptor` type is in scope).
+ *
+ * Keeping the name + label keys here — in the kernel leaf both the
+ * runner producers (Phase F.3/F.5) and the router selector consume —
+ * guarantees producer/consumer agreement without a second contracts
+ * package. Adding/renaming a key is a coordinated kernel change.
+ */
+
+/**
+ * Canonical Service Registry `name` every runner registers under. The
+ * router resolves this name to enumerate the runner pool.
+ */
+export const RUNNER_PLANE_SERVICE_NAME = 'xema-runner-plane' as const;
+
+/**
+ * Descriptor-`labels` keys a runner MUST advertise so the router can
+ * reconstruct its `RunnerRegistration`. Closed set; the mapping in the
+ * router fails-fast when a required key is missing or carries a value
+ * outside the corresponding closed enum.
+ */
+export enum RunnerPlaneLabelKey {
+  /** `RunnerKind` wire value (e.g. `cloud`, `customer-edge`). */
+  Kind = 'xema.runner/kind',
+  /** `RunnerMode` wire value (`embedded` | `local-module` | `remote`). */
+  Mode = 'xema.runner/mode',
+  /** `RunnerTransportMode` wire value (`push` | `pull`). */
+  Transport = 'xema.runner/transport',
+  /** Optional `DataLocality` wire value (`cloud` | `customer-private` | `gpu`). */
+  DataLocality = 'xema.runner/data-locality',
+  /** Optional `RunnerTrustTier` wire value (`untrusted` | `verified` | `trusted` | `system`). */
+  TrustTier = 'xema.runner/trust-tier',
+}
+
+/**
+ * The reserved `RunnerPlaneLabelKey` values, frozen for membership tests.
+ * Free-form runner labels (the {@link WellKnownRunnerLabel} tags and any
+ * operator-declared `key=value` pairs) MUST NOT collide with these —
+ * they are derived deterministically from typed registration fields, so a
+ * free-form label overriding one would let a runner mislabel its own
+ * kind/mode/transport. Producers fail-fast on collision.
+ */
+export const RESERVED_RUNNER_PLANE_LABEL_KEYS: ReadonlySet<string> = new Set(
+  Object.values(RunnerPlaneLabelKey),
+);
+
+/**
+ * Well-known capability/tag labels a runner advertises in its
+ * `RunnerRegistration.labels` (round-tripped onto its descriptor `labels`)
+ * so the router can match work by capability tag. These are DISTINCT from
+ * {@link RunnerPlaneLabelKey}: those reserved keys carry the runner's typed
+ * classifying dimensions (kind/mode/transport/locality/trust); these tags
+ * advertise discrete capabilities a runner does or does not have.
+ *
+ * Tag semantics are presence-style: a tag is "advertised" when the label
+ * map carries `key === RUNNER_LABEL_PRESENT`. The overall label space is
+ * OPEN — operators may add arbitrary `key=value` labels (e.g.
+ * `region=eu-west`) via config — but these are the kernel-known tags the
+ * default local runner and the scheduler agree on by name.
+ */
+export enum WellKnownRunnerLabel {
+  /** General-purpose default runner; eligible for unpinned work. */
+  Default = 'xema.runner/default',
+  /** Executes in-process / on the local host (dev + edge default). */
+  Local = 'xema.runner/local',
+  /** A Node.js runtime is available on the runner. */
+  Node = 'xema.runner/node',
+  /** A reachable Docker daemon is available on the runner. */
+  Docker = 'xema.runner/docker',
+  /** A GPU is available on the runner. */
+  Gpu = 'xema.runner/gpu',
+}
+
+/** Canonical value marking a presence-style runner tag as advertised. */
+export const RUNNER_LABEL_PRESENT = 'true' as const;
+
+/**
+ * The intrinsic tag set an in-process local-module runner (biome-host's
+ * supervisor) ALWAYS advertises. Each is deterministically true for a
+ * Node.js process running locally, so advertising them is never a false
+ * claim. Capability tags that depend on host provisioning the process
+ * cannot verify in-band — `docker`, `gpu` — are deliberately EXCLUDED;
+ * those are opt-in via operator-declared labels so the runner never
+ * advertises a capability it cannot honour (no silent over-claim).
+ */
+export function localModuleRunnerBaseLabels(): Record<string, string> {
+  return {
+    [WellKnownRunnerLabel.Default]: RUNNER_LABEL_PRESENT,
+    [WellKnownRunnerLabel.Local]: RUNNER_LABEL_PRESENT,
+    [WellKnownRunnerLabel.Node]: RUNNER_LABEL_PRESENT,
+  };
+}

package/src/runner/lib/runner-registration.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import { RunnerKind, RunnerKindSchema } from '../../policy';
+
+import { RunnerTransportMode } from './runner-mode';
+import { RunnerTrustTier } from './runner';
+
+/**
+ * High-level execution mode a runner declares at registration time
+ * (plan §6 Phase F, north-star §3 "three biome execution modes").
+ *
+ * This is the *biome execution mode* (where the biome physically runs)
+ * — DISTINCT from `RunnerTransportMode` (push vs pull, how the runner
+ * receives work) and from `RunnerKind` (the closed runner-classifier
+ * set that policy `routeHints.preferredRunnerKind` consults).
+ *
+ * Closed set; adding a fourth mode is a kernel change.
+ */
+export enum RunnerMode {
+  /**
+   * Runs inside `xema-kernel-server` itself — Phase F.1. The kernel
+   * registers a synthetic runner descriptor under this mode so the
+   * dispatcher sees embedded biomes as ordinary registry entries.
+   */
+  Embedded = 'embedded',
+  /**
+   * Sidecar process supervised by `biome-host-api`'s local-module
+   * supervisor — Phase F.2. The default for dev + first-party.
+   */
+  LocalModule = 'local-module',
+  /**
+   * Out-of-cluster runner reachable via event-hub Push or long-poll
+   * Pull — Phase F.3.
+   */
+  Remote = 'remote',
+}
+
+export const RunnerModeSchema = z.nativeEnum(RunnerMode);
+
+/**
+ * Coarse data-locality classifier carried on a runner registration so
+ * `Policy.routeHints` + the runner selector can refuse cloud fallback
+ * when an environment hard-pins customer-private execution.
+ *
+ * Closed set on purpose — anything finer-grained belongs on
+ * `RunnerRegistration.labels` (e.g. `region=eu-west`,
+ * `tenant=acme-finance`).
+ */
+export enum DataLocality {
+  Cloud = 'cloud',
+  CustomerPrivate = 'customer-private',
+  Gpu = 'gpu',
+}
+
+export const DataLocalitySchema = z.nativeEnum(DataLocality);
+
+/**
+ * Embedded biome registration — Phase F.1.
+ *
+ * Lives on a `RunnerRegistration` whose `mode === RunnerMode.Embedded`.
+ * The `xema-kernel-server` enumerates its built-in biomes (concept
+ * registry, shell built-ins, XVFS resolver) as a closed list at boot
+ * and surfaces them through this shape so downstream services can
+ * resolve `capabilityRef -> embedded biome`.
+ */
+export interface EmbeddedBiomeRegistration {
+  /**
+   * Stable biome identifier (`concept-registry`, `xema-shell-builtins`,
+   * `xvfs-resolver`, ...). Treated opaque by the kernel; the embedded
+   * biome owner picks the slug.
+   */
+  id: string;
+  version: string;
+  /**
+   * Capabilities this embedded biome exposes — same `<resource>:<verb>@<n>`
+   * grammar consumed by `xema-capability-router`.
+   */
+  capabilityRefs: string[];
+}
+
+export const EmbeddedBiomeRegistrationSchema = z.object({
+  id: z.string().min(1),
+  version: z.string().min(1),
+  capabilityRefs: z.array(z.string().min(1)),
+}) as z.ZodType<EmbeddedBiomeRegistration>;
+
+/**
+ * Provisioning entry for a single biome served by a runner. Discriminated
+ * by `mode` so consumers narrow once and read the only fields valid for
+ * that mode. The three variants align 1:1 with `RunnerMode`.
+ */
+export type BiomeProvisioning =
+  | EmbeddedBiomeProvisioning
+  | LocalModuleBiomeProvisioning
+  | RemoteBiomeProvisioning;
+
+export interface EmbeddedBiomeProvisioning {
+  mode: RunnerMode.Embedded;
+  embedded: EmbeddedBiomeRegistration;
+}
+
+export interface LocalModuleBiomeProvisioning {
+  mode: RunnerMode.LocalModule;
+  /** Slug of the local-module supervisor entry that owns the sidecar. */
+  moduleId: string;
+  version: string;
+  capabilityRefs: string[];
+}
+
+export interface RemoteBiomeProvisioning {
+  mode: RunnerMode.Remote;
+  /** Remote biome image + version (opaque to the kernel). */
+  imageRef: string;
+  version: string;
+  capabilityRefs: string[];
+}
+
+export const BiomeProvisioningSchema = z.discriminatedUnion('mode', [
+  z.object({
+    mode: z.literal(RunnerMode.Embedded),
+    embedded: EmbeddedBiomeRegistrationSchema,
+  }),
+  z.object({
+    mode: z.literal(RunnerMode.LocalModule),
+    moduleId: z.string().min(1),
+    version: z.string().min(1),
+    capabilityRefs: z.array(z.string().min(1)),
+  }),
+  z.object({
+    mode: z.literal(RunnerMode.Remote),
+    imageRef: z.string().min(1),
+    version: z.string().min(1),
+    capabilityRefs: z.array(z.string().min(1)),
+  }),
+]) as z.ZodType<BiomeProvisioning>;
+
+/**
+ * Healthcheck declaration a runner publishes alongside its registration.
+ * Carried as data (not a callable) so it survives the wire trip and so
+ * the kernel-server can decide policy (e.g. how often to probe).
+ */
+export interface RunnerHealthcheck {
+  /** HTTP path probed by the kernel-server (e.g. `/health/ready`). */
+  path: string;
+  /** Probe interval in seconds. */
+  intervalSeconds: number;
+}
+
+export const RunnerHealthcheckSchema = z.object({
+  path: z.string().min(1),
+  intervalSeconds: z.number().int().positive(),
+}) as z.ZodType<RunnerHealthcheck>;
+
+/**
+ * Top-level registration a runner publishes to the Service Registry at
+ * boot (Phase F.3). One row per runner instance; biomes hang underneath.
+ *
+ * Carry-forwards (Phase F.4/F.5):
+ *   - Keycloak service-account JWT validation
+ *   - Org-admin-countersigned `allowedEnvironments`
+ *   - RS256 signed job tokens with ≤60s TTL
+ */
+export interface RunnerRegistration {
+  instanceId: string;
+  mode: RunnerMode;
+  kind: RunnerKind;
+  labels: Record<string, string>;
+  region?: string;
+  /**
+   * IDs of `ExecutionEnvironment`s this runner is permitted to serve.
+   * Phase F.4 will countersign this list via the Keycloak service
+   * account; until then the runner is trusted to declare its own set.
+   */
+  allowedEnvironments?: string[];
+  /**
+   * Coarse data-locality classifier consumed by the runner selector
+   * + policy. Free-form labels go in `labels`.
+   */
+  dataLocality?: DataLocality;
+  /**
+   * Trust tier assigned at attestation time (Phase F.4). Absent until
+   * the kernel-server attests the runner; the policy bundle MAY gate
+   * sensitive capabilities to `Trusted`/`System` tiers only.
+   */
+  trustTier?: RunnerTrustTier;
+  /** Biomes served by this runner. */
+  biomes: BiomeProvisioning[];
+  healthcheck: RunnerHealthcheck;
+  /** Transport mode this runner uses to receive dispatched work. */
+  transport: RunnerTransportMode;
+}
+
+export const RunnerRegistrationSchema = z.object({
+  instanceId: z.string().min(1),
+  mode: RunnerModeSchema,
+  kind: RunnerKindSchema,
+  labels: z.record(z.string().min(1), z.string()),
+  region: z.string().min(1).optional(),
+  allowedEnvironments: z.array(z.string().min(1)).optional(),
+  dataLocality: DataLocalitySchema.optional(),
+  trustTier: z.nativeEnum(RunnerTrustTier).optional(),
+  biomes: z.array(BiomeProvisioningSchema),
+  healthcheck: RunnerHealthcheckSchema,
+  transport: z.nativeEnum(RunnerTransportMode),
+}) as z.ZodType<RunnerRegistration>;