Runtime context

The `AppContext` passed to server executors.

Every server executor receives an AppContext as its second argument:

import type { AppContext } from '@voltro/runtime'

export default async (input: Input, ctx: AppContext) => {
  const subject = ctx.request.subject
  const rows = await ctx.store.query(/* ... */)
}

Query, mutation, action, stream, and workflow files export both descriptor metadata and the default executor. The default executor receives ctx; descriptor objects stay data-only and browser-safe.

ctx.request

Per-call runtime metadata:

ctx.request.subject   // user, apiKey, system, or anonymous subject
ctx.request.traceId   // trace id shared with client/server spans
ctx.request.spanId    // current span id when tracing is active
ctx.request.clientId  // WebSocket connection id for RPC calls

Most auth and tenant checks read ctx.request.subject:

const tenantId = ctx.request.subject.tenantId
if (ctx.request.subject.id == null) throw new Error('sign-in required')

ctx.store

The typed mutation store. It applies schema mixin behavior for audit(), tenant(), and softDelete() where configured.

await ctx.store.insert('notes', { title: 'Hello' })
await ctx.store.update('notes', noteId, { title: 'Updated' })
await ctx.store.delete('notes', noteId)

const rows = await ctx.store.query(database.notes.descriptor)

ctx.store.query returns the row type the builder already knew — database.notes resolves to that table's row, so rows[0].title is a string with no cast. A hand-built descriptor still resolves to the untyped Row.

Mutations receive a transactional store view. Actions and streams receive a normal store view; writes from them are not automatically rolled back as one unit.

ctx.load / ctx.loadMany — request-scoped batching

relations() + .with() is the right answer whenever the shape of the related data is known statically: it compiles to ONE query. Reach for it first.

This is for the case it cannot express — assembly whose shape depends on the DATA. A breadth-first walk over a tree is the canonical example: each level's ids come from the level above, so no declarative relation spec covers it, and the natural code is one query per node.

let level = [await ctx.load('nodes', rootId)]
while (level.length > 0) {
  const childIds = level.flatMap((n) => n?.childIds ?? [])
  if (childIds.length === 0) break
  level = [...await ctx.loadMany('nodes', childIds)]
}

Every load issued in the same tick for the same table is coalesced into one WHERE id IN (...), so that walk costs one query per LEVEL, not per node. Repeated ids — a diamond where two parents share a child — are fetched once. A missing row is null rather than a throw, because a dangling edge in a graph walk is usually data; use .one() when absence is an error.

The cache lives exactly as long as the request. That is a correctness requirement, not a tuning choice: a longer-lived cache would serve one subject's rows to another (a data-isolation bug on a tenant-scoped store) and would go stale across a mutation in the same request.

ctx.cache

Async cache facade for request handlers:

const value = await ctx.cache.wrap(
  `summary:${id}`,
  { ttlMs: 60_000, tags: ['notes'] },
  () => computeSummary(id),
)

await ctx.cache.invalidateTag('notes')

Mutation target metadata can invalidate matching tagged cache entries automatically.

ctx.kv

Durable key-value facade — always present, and unlike ctx.cache its entries are never evicted for capacity (they live until deleted or their TTL lapses). Use it for state you can't recompute; the default backend on a sql app is the database, so values survive restarts.

const state = await ctx.kv.getOrElse(`onboarding:${userId}`, () => ({ step: 0 }))
await ctx.kv.set(`onboarding:${userId}`, { step: state.step + 1 })

get / getOrElse / set (optional { ttlMs }) / delete / has / list(prefix) / clear. See Durable key-value.

ctx.webhooks

Present only when the webhooks plugin is configured. Plugin-specific packages expose typed helpers for their optional context slots; the core runtime keeps the slot structurally typed so apps do not pay for unused plugins.

ctx.workflows

Present when the API app has discovered workflows. It starts durable work and controls existing runs:

const run = await ctx.workflows.start('notes.summarise', { noteId })
await ctx.workflows.signal({ id: run.id }, 'approval', { approved: true })
const approval = await ctx.workflows.update({ id: run.id }, 'approve', { decision: true })
const latest = await ctx.workflows.query('notes.summarise', run.executionId)
const snapshot = await ctx.workflows.wait('notes.summarise', run.executionId)

Use signal(...) for fire-and-forget external events. Use update(...) when the caller needs a tracked result from the workflow's awaitUpdate(...) handler.

Inside a mutation, ctx.workflows.start(...) queues the actual launch until after the transaction commits. If the mutation rolls back, the workflow is not started. ctx.workflows.run(...) and start(..., { wait: true }) are intentionally rejected inside mutation transactions.

Workflow starts record their start source (workflow-rpc, app-context, schedule:<name>, incoming:<id>, or inspect). Request-backed starts also carry the current request trace, and authenticated request starts carry the resolved subject into the run context. Keep authorization-critical tenant/user ids in the workflow payload so resumed work stays deterministic.

Effect Services

Server executors may return Effects. Actions and streams receive the base platform layer, including HttpClient. AI helpers are imported from @voltro/ai:

import { generateText } from '@voltro/ai'
import { Effect } from 'effect'

export default (input: { prompt: string }) =>
  Effect.gen(function* () {
    const { text } = yield* generateText({ prompt: input.prompt })
    return { text }
  })

Writing a wrapper that PROVIDES a service

A helper that provides a service must be generic over R and subtract the tag it provides, or it silently narrows what callers may pass it. The failure mode is confusing because it shows up at the CALL site, not in the wrapper:

import { Context, Effect } from 'effect'

class Tenant extends Context.Tag('Tenant')<Tenant, { readonly id: string }>() {}

// WRONG — `R` defaults to `never`, so this only accepts effects that need
// nothing else. Pass it an effect that also needs `Db` and it stops compiling.
const withTenantBad = <A, E>(id: string, effect: Effect.Effect<A, E>) =>
  Effect.provideService(effect, Tenant, { id })

// RIGHT — generic over `R`, and the return type SUBTRACTS the tag it provided.
const withTenant = <A, E, R>(
  id: string,
  effect: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, Exclude<R, Tenant>> =>
  Effect.provideService(effect, Tenant, { id })

Exclude<R, Tenant> is what makes the wrapper composable: the caller's remaining requirements pass through untouched, and only the tag you actually supplied disappears. Without it, the wrapper's own signature dictates the caller's entire requirement set.

The same rule applies to any callback the framework takes from you (an AI tool body, a media generator, a workflow step): declare its R as unknown rather than letting it default to never, then let the framework's own bridge discharge it. A callback typed Effect<A, E, never> cannot use ANY service, which is rarely what you meant.

A wrapper generic over R hides a requirement it gained

The subtraction above is one direction. The other bites when a helper starts USING a service inside its body: R is inferred from the effect the caller hands in, so a newly required tag is not added to it and the compiler has nothing to compare. The program builds and fails at run time with Service not found: @voltro/EffectStore.

// `R` comes from the effect the caller passes, so adding `EffectStore` INSIDE
// the body changes nothing the signature says — and nothing type-checks it.
const withTeam = <A, E, R>(
  id: string,
  body: (team: Team) => Effect.Effect<A, E, R>,
): Effect.Effect<A, E, Exclude<R, SubjectService> | EffectStore> =>   // ← name it here
  Effect.gen(function* () {
    const store = yield* EffectStore
    …
  })

Worth a grep after any change that moves handlers onto a service — a helper generic over R is exactly the shape that stays green through it.

The store on the Effect channel

yield* EffectStore carries the same operations as ctx.store, with the failures on a typed channel instead of becoming defects. The names line up one to one, with one that does not read like its Promise spelling:

ctx.store yield* EffectStore note
query(d) query(d) typed rows, not Record<string, unknown>
one / maybeOne / first same one fails with NoRowFound
insert / insertMany same
update / updateMany / patchJson same
delete(t, id) delete(t, id) soft, on a softDelete() table
delete(t).where(p).hard() deleteMany(t, { where: p }) physical — the set-based form never soft-deletes
hardDelete(t, id) hardDelete(t, id)
upsert / insertIgnore (+ WithOutcome) same
transactional(fn) transactional(fn) fn returns an Effect

The last two rows are the ones worth reading twice. The KEYED delete(t, id) honours a softDelete() mixin; the SET-BASED deleteMany never has — it is the physical remove, and therefore the Effect form of the fluent delete(t).where(p).hard().

one does not take an onMissing. It fails with NoRowFound on its own channel, which is strictly more precise — map it where you want your own error:

const store = yield* EffectStore
const team = yield* store.one(database.teams.where(eq('id', input.teamId)).descriptor)
  .pipe(Effect.catchTag('NoRowFound', () => Effect.fail(new TeamNotFound({ id: input.teamId }))))

Where the Effect store does NOT fit

Two bodies pin their failure channel to never, and there Effect.promise is the correct statement rather than a shortcut — a store failure is a defect, and the retry policy is built on that:

  • a step({ execute }) with no error: schema — Error defaults to Schema.Never, so StoreError has nowhere to go;
  • a *.tool.tsx handler, whose contract is Effect<string, never, unknown>.

Declare an error: on the step and the channel widens:

step({ execute: Effect.promise(() => ctx.store.query(d)) })                    // channel is `never`
step({ error: Schema.Union(StoreOperationFailed), execute: Effect.gen(…) })    // now it can carry one

voltro doctor knows both cases and stays quiet in them.

Context By Primitive

Server file Transaction Typical store usage External I/O Returns
*.query.server.ts No Read/query Avoid Query descriptor or computed value
*.mutation.server.ts Yes Atomic writes Avoid Unary output
*.action.server.ts No Optional, non-atomic Yes Unary output
*.stream.server.ts No Optional, non-atomic Yes Stream, Effect<Stream>, or Promise<Stream>
*.workflow.tsx Step-specific Durable reads/writes Yes, inside activities Workflow result

Use mutations for atomic state changes, actions for one-shot side effects, streams for progressive element output, and workflows for durable multi-step work.