Reference

Coding environment

Workspace IDE, source assets, runtime SDK, authored code surfaces, custom connectors, build pipeline, local dev, tests, diagnostics, and deploy flow.

Vadyl's coding environment is a canonical API consumer, peer to the CLI and SDKs. Files are source-asset entities, editor types come from contract projection, builds produce signed artifacts, and deployments publish through the same branch/proposal/publication lifecycle as schema changes.

Environment surfaces

Surface	Coverage
Workspace IDE	Browser-native file tree, Monaco projection, extraLibs from ContractProjection, run/test/deploy actions.
Source assets	Folders, files, modules, blobs, content-addressed storage, branchable metadata.
Runtime SDK	Language-neutral bridge projected into TypeScript first, then Python, Go, Rust, C#, and future languages.
Build pipeline	Language adapter, diagnostics, unit artifact builder, signatures, publication finalization, rollback.
Local development	Dev descriptors, local worker, CLI parity, sandbox publish/invoke, contract projection invalidation.
Custom connectors	WIT world, Wasm component, host imports, conformance, memory, publication, binding.
Testing	Unit tests, live tests, sandbox tests, runtime invocation E2E, contract drift tests.
Developer observability	Build logs, invocation traces, bridge errors, source maps, operational trails, explainers.

Authoring surfaces

Execution surface	What you write
`CoreHandler`	Synchronous authored logic with host-owned transaction participation.
`DurableWorkflow`	Journaled workflow with worker-executed steps, signals, compensation, and replay.
`EventConsumer`	Publication-aware event consumer with outbox-backed delivery and at-least-once semantics.
`ScheduledJob`	Cron, interval, or one-shot scheduled job body under scheduler kernel authority.
`WebhookHandler`	Handler invoked after signature verification, idempotency receipt, and receiver policy checks.
`EdgeHandler`	Reduced-authority low-latency stateless handler with build-time and runtime import gates.
`ManagementHandler`	Privileged authored surface for schema, branching, publication, and platform mutation authority.

Runtime topology surfaces

Build artifacts target the seven authored-code surfaces, then runtime fabric realizes them as project execution surface kinds. The topology vocabulary also includes API ingress and realtime gateway surfaces.

Project surface	Meaning
`Unspecified`	Fail-closed default. Never silently resolves or applies.
`ApiIngress`	Project HTTP API ingress surface; commonly load-balanced and scaled on request pressure.
`CoreHandler`	Authored core handlers in the project runtime topology; can scale independently from consumers and jobs.
`DurableWorkflow`	Authored durable workflows in the project runtime topology; pinned to publication and governed by workflow runtime policy.
`EventConsumer`	Authored event consumers; commonly autoscaled on queue depth, consumer lag, or custom PCG measures.
`ScheduledJob`	Authored scheduled jobs served by platform scheduling operators; often fixed or tightly capped.
`WebhookHandler`	Authored inbound webhook handlers; can be separately exposed, load balanced, and autoscaled.
`EdgeHandler`	Constrained authored edge handlers with edge-resource policy and distribution-origin integration.
`ManagementHandler`	Privileged authored management handlers; usually fixed, private, and heavily governed.
`RealtimeGateway`	Project realtime WebSocket/SSE subscription gateway; scales on connection and fanout pressure.

Core handler example

src/handlers/orders/charge.ts

import { handler } from "@vadyl/runtime";

export default handler.core(async (ctx, input: { orderId: string }) => {
  const order = await ctx.entities.Order.read(input.orderId);

  const charge = await ctx.connections.stripe.createCharge({
    amount: order.total,
    currency: order.currency,
    customer: order.customerId,
    idempotencyKey: `charge:${order.id}`,
  });

  await ctx.entities.Order.update(order.id, {
    status: "paid",
    chargeId: charge.id,
  });

  return { ok: true, chargeId: charge.id };
});

Build and publish flow

vadyl source file put src/handlers/orders/charge.ts --content @charge.ts
vadyl build preview --unit orders.charge
vadyl build publish --unit orders.charge
vadyl branch commit --message "Add order charge handler"
vadyl deploy preview --target production
vadyl deploy apply --target production --ramp 5%,25%,50%,100% --bake 10m

Build output

{
  "artifactId": "art_123",
  "unit": "orders.charge",
  "runtimeFamily": "nodejs",
  "surface": "CoreHandler",
  "diagnostics": [],
  "signature": { "keyId": "kr_2026_05", "algorithm": "ed25519" },
  "publicationCandidate": { "sourceCommitId": "commit_789" }
}

Rules

Authored code reads/writes entities through the runtime bridge, never raw databases.
External calls go through governed connections, never arbitrary egress.
Long-running logic uses durable workflows, never process memory timers.
Edge handlers use a narrower capability set and forbidden-import validation.
Management handlers require elevated grants and are audited as platform mutations.
Every artifact is tied to source commit, contract version, publication version, and runtime descriptor.

Limits & quotas

Connectors & WIT