The Runtime
The runtime executes your compiled spec. It is a single, ordered execution pipeline that runs identically for every query, mutation, and route invocation.
Why this exists
When access enforcement, idempotency gating, and business logic are not separated, each one ends up implemented inconsistently. Some access checks live in middleware, others in route handlers, others inside business logic. Any gap is a security vulnerability. Idempotency is implemented per-endpoint with no shared key model. Response shapes differ across handlers, forcing surface adapters to handle a different structure from every call.
The Gooi runtime addresses this by defining a kernel that is the single, authoritative orchestration core. Access enforcement, replay gating, dispatch, and envelope assembly happen in the kernel, exactly once, for every invocation. Semantic engines implement domain logic only. They never reimplement kernel concerns.
The execution pipeline
Every invocation follows the same five-step pipeline.
1. Validate input schema
2. Evaluate access (auth context × declared roles)
3. Check replay store (mutations only)
4. Dispatch to semantic engine (domain / projection / render runtime)
5. Assemble canonical ResultEnvelope
Surface adapters call runtime.invoke() with a typed input. The kernel executes the pipeline and returns a ResultEnvelope. The surface adapter translates the envelope to its native response format (HTTP response, CLI output, etc.).
The kernel and semantic engines
The kernel owns orchestration. The semantic engines own domain logic.
Kernel responsibilities:
- Input schema validation
- Access enforcement
- Replay/idempotency gating (mutations)
- Canonical envelope assembly
Semantic engine responsibilities:
- Domain runtime: executes action step graphs, calls capability ports, evaluates guards
- Projection runtime: executes projection strategies against the compiled IR
- Guard runtime: evaluates structural and semantic guard rules
- Render runtime: resolves view node trees for route invocations
Semantic engines never reimplement kernel concerns. Adding a new semantic engine does not change the kernel.
The ResultEnvelope
Every invocation returns a canonical ResultEnvelope.
type ResultEnvelope =
| { status: "ok"; output: unknown }
| { status: "rejected"; violations: Violation[] }
| { status: "replayed"; output: unknown }
| { status: "error"; error: RuntimeError };
replayed means the kernel found a matching entry in the replay store and returned the cached result without re-executing. This is idempotency enforcement at the platform level.
Adoption levels
You adopt the runtime at the depth you need.
| Level | Entry point | What you get |
|---|---|---|
| L0 | GooiAppSpec types | Typed contracts, zero runtime |
| L1 | compileApp() | Deterministic compiled artifacts |
| L2 | createAppRuntime() | Full kernel inside your existing server |
| L3 | defineApp → compileApp → createAppRuntime | End-to-end platform |
Each level is a strict superset of the one below it. Moving from L2 to L3 is an addition, not a replacement.
What's next
- L0: Contract-first: import typed contracts with zero runtime dependency
- L1: Compile-first: produce deterministic compiled artifacts
- L2: Embedded Runtime: run the full kernel inside your existing server
- L3: Full Platform: the complete end-to-end arc