Authored runtime

Vadyl runs your authored code in a language-neutral runtime where every interaction with the platform is typed, governed, and observable. There are exactly seven canonical execution surfaces. Together they cover everything an application needs to do, with no escape hatch into ambient I/O.

The seven surfaces

1. Core handler — synchronous request-time logic invoked through the API surface. Read entities, mutate, call governed connections, return.
2. Durable workflow — long-running orchestration with journaled steps, signal waits, and saga compensation. Survives process restarts.
3. Event consumer — subscribes to canonical entity events or custom platform events. Idempotent under at-least-once delivery.
4. Scheduled job — cron, interval, or one-time fires. Durable, retryable, observable through the same lifecycle as handlers.
5. Webhook handler — verified inbound webhooks with signature checks and idempotency receipts.
6. Edge handler — constrained CDN-edge logic for low-latency request shaping. Cannot read or write entities; cannot start workflows. See Edge constraints.
7. Management handler — privileged surface for schema transitions, branching ops, runtime publication mutations, installable surface publishing. Gated by management authority.

Topology and scaling

Execution surface is not deployment topology. A core handler, event consumer, scheduled job, webhook handler, realtime gateway, and edge handler can each carry separate Runtime Fabric policy: shared pool, per-project pool, per-surface service, or named scale group. The policy declares desired instances, autoscale rules, load balancing, CPU, memory, storage, resource class, accelerator class, and edge budgets in canonical terms. Substrate connectors translate that intent into ECS services, Kubernetes workloads, Cloud Run services, edge isolates, or other native shapes.

See Project scaling and Runtime Fabric for the workload-realization side of the authored runtime.

The runtime bridge

Authored code reaches the platform through a typed runtime bridge — ctx — never through raw drivers or ambient APIs.

export default handler.core(async (ctx, input: { orderId: string }) => {
  // Entities — typed, access-evaluated, cache-aware
  const order = await ctx.entities.Order.read(input.orderId);

  // Governed connections — secret-ref, capability-checked, audited
  await ctx.connections.email.send({
    to: order.customerEmail,
    template: "order-paid",
    data: { order },
  });

  // Workflows — durable, journaled
  await ctx.workflows.fulfillOrder.start({ orderId: order.id });

  // Events — outbox-backed, at-least-once
  await ctx.events.emit("order.paid", { orderId: order.id });

  return { ok: true };
});

Every method on ctx is canonical. There are no escape hatches. You cannot open a raw socket; you cannot import the Postgres driver directly; you cannot read environment variables outside the secret resolver. This is by design — see Governance.

Capability matrix

Each execution surface has a typed capability set. The bridge enforces it at three layers — language SDK types, build-time module allowlist, and runtime isolate guards.

Edge constraints

Edge handlers run at the CDN edge — milliseconds away from users — and are deliberately constrained. They handle request shaping, geo routing, rate-limit prechecks, session/auth prechecks, and cache mediation. They cannot read or write entities, start workflows, publish events, or call non-edge-tier governed connections. Serious business logic runs in core handlers in the main host, not at the edge.

Workflow determinism

Workflows must be deterministic to enable replay-based recovery. Vadyl provides journaled accessors: ctx.now(), ctx.random(), ctx.step(...), ctx.waitForSignal(...), ctx.compensate(...). Calling Date.now() directly inside a workflow is rejected at compile time.

Worker process model

Authored code runs out-of-process in language-specific workers (Node.js for TypeScript today). Workers communicate with the host over named pipes (Windows) or Unix domain sockets (Linux/macOS), using a typed gRPC contract. Exactly-once invocation dispatch is enforced via interlocked compare-exchange on pending invocation claims.

Drain semantics

On redeploy, workers receive a canonical VADYL_DRAIN signal on stdin and stop accepting new invocations. In-flight invocations are given a configurable grace period to complete; if they exceed it, the worker is killed and the in-flight workflow steps recover via journal replay.