---
title: "Runtime"
url: /runtime
---

# Runtime

> The kernel every move passes: one gate, Verbs run as Functions and Workflows, Triggers and time, and every change sent out as an Event.

The Runtime is the kernel every move passes through: one gate that identifies, decides, prices, guards, commits and acts outside. [Verbs](/reference/platform.md#verb) run there as [Functions](/patterns.md#function-api) and [Workflows](/workflow.md), started by calls, [Triggers](/patterns.md#the-blocks) and time; every change leaves as an Event.

## Capability families
Every product runs on the same kernel, and it is the only writer of the record. A fact, its [Event](/reference/platform.md#event), its meter line and its audit entry commit together, or none of them do.

| Family | What it gives every product |
| --- | --- |
| The gate | One path for every call, run and inbound Event: identify, decide, price, guard, commit, then effects. The first step that fails answers, and the call costs nothing |
| Verbs and the [Action](/workflow.md#the-lifecycle) | Every Verb answers one [Action](/reference/platform.md#action): done, Pending with its reason, or refused with a cure. Idempotency keys, cancel, `Prefer: wait` and batches work the same on all of them |
| Function kinds | Code, generative, agentic and human, each a [Function](/reference/platform.md#function) behind one Verb and one price. A step escalates to the next kind when its check fails, and the caller sees the same Action |
| The model router | Every generative and agentic call goes through one router: model routing, fallbacks, a Customer's own model keys, token metering and the `Max-Cost` ceiling |
| Workflows | Durable code and state machines: steps that run once, waits of weeks, child Actions, compensation, each run pinned to the [Version](/reference/platform.md#version) it started on |
| Triggers | What starts work with no call: an Event, a schedule, or a Thing entering a state. An inbound webhook and a crossed threshold each write an Event, so they start work the same way |
| Time | Clocks as data: durations, schedules in each Customer's timezone, business calendars, deadlines that lapse, and test clocks in the [Test twin](/reference/platform.md#test-twin) |
| Effects | Every outside act as a durable intent: recorded in the commit, sent once by its idempotency key, acknowledged, retried, compensated on failure, then reconciled |
| Events | The change feed in order, [Watches](/reference.md#events) and signed webhooks out, verified webhooks in, live subscriptions, and signals sent into a waiting run |

The gate's six steps are one order for every [Interface](/every-product.md). The call contract's twelve checks are the same path, rendered for HTTP. Decide and price give the caller one answer: the decision reads the price, and the price step reserves it.

| Step | It answers | When it fails |
| --- | --- | --- |
| Identify | Which principal, for which Customer, under which [Key](/reference/platform.md#key) or mandate | 401, before anything else is read |
| Decide | The one policy decision: allowed, pending, or refused with a cure | 403, or a Pending Action that waits for a person |
| [Price](/reference/platform.md#price) | Reserves the price the decision read, against the plan, the credits and the call's `Max-Cost` | 402, with the offers that lift it |
| Guard | The lifecycle state, uniqueness, rate limits, brakes and input types | 409, 429 or 400 |
| Commit | The fact, its Event, its meter line, its audit entry and its intents, as one | Nothing is written, and nothing is billed |
| Effects | Each recorded intent, sent outside once | The intent retries, then compensates; the fact stands |

## Lifecycles and states
| Thing | States | What moves it |
| --- | --- | --- |
| An Action | `pending`, then `done`, `failed` or `cancelled`; `refused` never starts | Its steps, a cancel, or a check at the gate |
| A wait | `Running`, `AwaitingWorker`, `AwaitingInput`, `AwaitingTime`, `AwaitingSource`, `AwaitingAction`, `AwaitingApproval`, `Retrying` | The step the run is on; the reason names who holds the ball |
| A run across deploys | Pinned to its Version until it ends | Nothing: a deploy moves new calls at once, and old Versions run until their work closes |
| An effect | `recorded`, `sent`, `acknowledged`, `reconciled`; or `retrying`, `failed`, `compensated` | The outside party's answer, then what the outside later reports |
| A webhook delivery | `queued`, `delivered`; or `retrying` for 3 days, `parked`, `replayed` | The receiver's answer, then a replay from the developer portal or the API |
| A clock | `running`, then `fired` or `lapsed`; `paused` on a business calendar's closed hours | Time, or a test clock advanced in the Test twin |
| A live subscription | `open`, `behind`, `closed` | The client; a client that falls behind resumes from its last `seq` |

## What you declare, what the platform does
| You declare | The platform does |
| --- | --- |
| A Verb, its Function kind and its `returns` | Serves it on every [Interface](/every-product.md), types its output everywhere, and meters it once |
| A `workflow()` or a `machine()` | Keeps every step's result, survives restarts, waits for weeks, and pins each run to its Version |
| An `on` line: an Event, a schedule, or a state | Starts the Verb once per Event, or once per Customer in that Customer's timezone |
| A duration, a deadline or a business calendar | Runs the clock, fires `after`, lapses a window, and offers test clocks in the Test twin |
| A prompt and its `returns` | Routes the model, falls back on a failure, uses a Customer's own model key when one is set, and counts tokens |
| A Watch, or a [Source](/patterns/dataset-api.md#how-a-field-is-filled) that delivers | Signs, retries and replays deliveries out; verifies deliveries in, and writes each as an Event before anything runs |
| Nothing else | The gate's order, idempotency, the commit invariant, effects, reconciliation, cutover and the evidence of every decision |

### Example
A won Deal starts the kickoff. The run drafts a plan, waits up to seven days for the Customer's CRM to confirm the company, then commits once.

```ts title="kickoff: a week on the clock, resumed by an Event"
export default define({
  …
  sources: { crm: { system: 'crm', scope: 'customer' } },
  Deal: {
    …
    kickoff: workflow(async ($, deal) => {
      const { plan } = await $.generative('Draft the kickoff plan for {company.name}', deal,
        { returns: { plan: 'string' } })
      await $.wait({ event: 'Company.updated', where: { id: deal.company }, within: '7d' })
      const at = await $.step('stamp it', () => new Date().toISOString())
      return { plan, at }
    }),
  },
  on: { 'Deal.won': 'Deal.kickoff' },           // Trigger: what reacts to a change
  …
})
```

```http title="GET /actions/act_8, while it waits"
HTTP/1.1 200 OK
X-Cost: price=0, currency="USD"

{
  "id": "act_8",
  "verb": "Deal.kickoff",
  "status": "pending",
  "reason": "AwaitingSource",
  "until": "2026-11-02T15:00:00Z",
  "poll": "/actions/act_8"
}
```

When the CRM's change arrives as `Company.updated`, Observed, the run resumes and stamps its time once. If the seven days pass first, the wait lapses and the run takes its next step.

## Contracts with the other subsystems
Every other subsystem proposes; the Runtime commits.

| Subsystem | What the Runtime takes from it | What the Runtime gives it |
| --- | --- | --- |
| Definition and compile | A compiled Version: routes, machines, prices, Triggers, staffing | Every output stamped with that Version's [Digest](/reference/platform.md#digest); every run pinned to it |
| Identity, access and policy | One answer per move, at the `decide` step | The principal and the mandate on every Action and Event |
| Model and records | Nouns, lifecycles and the rules on history | The only writes to the record; every projection rebuilds from its Events |
| Data and Sources | Source reads and the [Mappings](/patterns/dataset-api.md#how-a-field-is-filled) that fill fields | Reads as steps, refreshes on schedule, write-backs as effects, outside changes as Observed Events |
| Work | Tasks, reviews and sign-offs, as steps | `$.human` raises a task, and the run waits `AwaitingWorker` until it is done |
| Commerce | The price, the [Entitlement](/reference/platform.md#entitlement) and the meter rules | The meter line in the commit; charges and refunds on Stripe as effects; `charged` on the Event an outcome bills at |
| Interfaces and distribution | One Action and one [Problem](/reference.md#errors) to render | The same reply on HTTP, MCP, the SDK, the CLI and webhooks, and live subscriptions |
| Trust and operations | The Test twin, brakes and rate limits | A trace per Action, the evidence of every decision, and replay |

## What Customers and their agents meet
- **One Action, everywhere.** A fast Verb answers done. A slow one answers 202 with `poll`, and `Prefer: wait=30` holds the call open.
- **A refusal before any work.** A refused call costs nothing and names what lifts it: a payment, the clock, or a person.
- **A ceiling they set.** `Max-Cost` refuses a priced call above it before it runs, and stops a metered run at it.
- **Retries that are safe.** A write sent again with the same `Idempotency-Key` runs once and is billed once.
- **Who holds the ball.** A waiting run names its reason and its deadline, and `POST /actions/{id}/cancel` stops it at no charge.
- **No polling.** An agent subscribes to its Action or to the change feed and resumes on the Event. A Watch delivers the same Events, signed and in order.
- **A stable run.** A run that starts on one Version finishes on it, whatever deploys meanwhile.

---

One gate, one commit and one Action, so every Interface tells the same story about every move.