Build & start

voltro build and voltro start — production builds, SSG pre-render, the SSR bundle, ISR cache.

voltro build produces a production artefact; voltro start serves it. Two commands, clean separation.

`voltro build <appDir>`

voltro build apps/acme/web
voltro build .                  # current dir

What it does for a web app:

vite build against .framework/ — produces dist/ with chunked client bundle.
Pre-renders static pages — every page with renderMode: 'static' is rendered to HTML once + lands at dist/<path>/index.html.
Pre-builds the SSR bundle — every page module compiled to dist/server/ssrEntry.js so voltro start doesn't need a Vite middleware loader at runtime.
Copies public/ into dist/.

For api apps, voltro build precompiles the whole handler closure — every procedure, workflow, subscriber, reaction, aggregate, agent, webhook, cron, startup, app.config, and their shared database/lib deps — into a single esbuild bundle at .framework/dist-api/apiEntry.js (the framework + npm deps stay external). voltro serve loads that bundle automatically at boot and resolves every handler from it, so production never transpiles TypeScript at runtime. Without a build, voltro serve still loads each source module on demand (via the tsx loader) exactly as voltro dev does — the build is an optimisation, not a requirement.

voltro build takes a single optional app directory and parses no flags — the SSR bundle is always attempted, and the SSG pre-render always runs for static-mode pages.

Output layout

apps/acme/web/.framework/dist/
├── index.html                          # SPA shell fallback
├── about/index.html                    # pre-rendered static page
├── blog/first-post/index.html          # SSG via getStaticPaths
├── assets/
│   ├── index-abc.js                    # main client bundle
│   ├── index-abc.css
│   └── island-LikeButton-def.js        # per-island chunks (interactive: 'islands' pages)
└── server/
    └── ssrEntry.js                     # SSR bundle for voltro start

Unresolvable optional peers

The SSR bundle inlines everything it reaches (ssr: { noExternal: true }), which is what lets a production web image ship without a framework dependency tree. A package that cannot be resolved at all is externalised instead of failing the build — almost always an uninstalled optional native peer reached through a library's Node entry point:

Rolldown failed to resolve import "canvas" from ".../konva/lib/index-node.js"

konva's main is its Node build, which requires the optional canvas; its browser field points at one that does not. An app that never renders to a canvas server-side has nothing to install, and there is no app-side workaround: making the import dynamic does not help (the bundler must still resolve it to form the chunk), and renderMode: 'spa' does not either — the generated router imports every page statically, so the module is in the SSR graph whatever the render mode.

Every specifier externalised this way is named on the success line:

[voltro:build] SSR bundle ready { path: 'dist/server/ssrEntry.js', externalizedOptionalPeers: 'canvas' }

Read that list. Externalising is right for an optional peer you never use, and wrong for a dependency you forgot to install — it turns a build failure into a runtime one, and only you can tell the two apart. Framework packages (@voltro/*, @effect/*, effect) are never externalised.

`voltro start <appDir>`

voltro start apps/acme/web              # serves the build output
PORT=8080 voltro start apps/acme/web

What it does:

Reads app.config.ts.port (or PORT env var) for the listen port.
Walks dist/ to discover pre-rendered HTML files.
Loads the SSR bundle from dist/server/ssrEntry.js. Falls back to Vite middleware mode if absent.
Starts an http.Server that:
- Serves pre-rendered HTML for matched URLs.
- Serves static assets from dist/assets/, dist/_voltro/.
- Renders SSR pages per request via the SSR bundle.
- Reads / writes ISR cache for renderMode: 'isr' pages.

Flags + env vars

Flag / env	Notes
`PORT=8080`	Override the listen port.
`SSR_CACHE=postgres`	Use the Postgres-backed ISR cache. Requires the web process to also have a database in its environment — `DB_URL` (what the templates set), `DB_PRIMARY_URL`, `DB_HOST` or `PG_HOST`. Without one, `voltro start` aborts on `NODE_ENV=production`/`staging` and warns loudly elsewhere; it no longer falls back to the in-memory cache in silence. Default is in-memory.
`VOLTRO_INSPECT=off`	Disable the inspect HTTP endpoints in production.
`VOLTRO_INSPECT_TOKEN=…`	Bearer token guard on the inspect endpoints.

Per-request routing logic

For a request to /foo:

1. dist/foo/index.html exists? → serve it.
2. URL matches a static asset? → serve from disk.
3. URL matches a registered query?
     - renderMode 'ssr' → render fresh via SSR bundle.
     - renderMode 'isr' →
         - cache HIT (fresh) → serve cached.
         - cache HIT (stale) + staleWhileRevalidate → serve cached + bg refresh.
         - cache MISS → render, store, serve.
     - renderMode 'static' (no pre-render found) → serve SPA shell.
4. None of the above → 404 via not-found.tsx.

The response includes a x-voltro-rendered-by header (prerender / ssr / isr) + cache state.

ISR cache backends

SSR_CACHE=memory voltro start         # default — per-process, doesn't survive restart
# Postgres-backed cache — the web process needs a database in its env. Any of
# the usual variables works; DB_URL is what the templates set.
SSR_CACHE=postgres DB_URL=postgres://… voltro start
SSR_CACHE=postgres PG_HOST=… PG_PORT=… PG_USER=… PG_PASSWORD=… PG_DATABASE=… voltro start

For multi-instance + horizontal scale → Postgres. The cache table is auto-created on first boot.

This used to recognise PG_HOST and nothing else. An app configured the documented way — SSR_CACHE=postgres plus DB_URL — silently got the per-process memory cache, announced as isr cache backend: memory (per-process): an info line that reads like the default rather than like a refusal. Both the cache and the CDC invalidator go through the same connection resolver as everything else now, so DB_URL / DB_PRIMARY_URL / DB_HOST / PG_HOST all work — and PG_SSL comes with them. Asking for the postgres cache and getting memory is now a boot failure in production, not a log line.

Tenant-aware ISR

Pages with tenantAware: true get separate cache entries per tenant. The cache key becomes <pathname>|tenant=<tenantId>. See Render modes.

CDC invalidation

For pages with cacheInvalidatesOn: ['table', …], voltro start reads Postgres logical replication. Writes to listed tables invalidate every matching cache entry. Requires SSR_CACHE=postgres + wal_level=logical.

If routes declare cacheInvalidatesOn and the web process has no database in its environment, boot now WARNS and names those routes — they fall back to plain revalidate staleness. That gap used to be reported at debug, which is invisible at the default level and indistinguishable from live invalidation working.

Graceful shutdown

voltro start handles SIGTERM:

Stop accepting new connections.
Wait up to SHUTDOWN_GRACE_MS (default 30s) for in-flight requests to finish.
Close active WebSocket connections (the client auto-reconnects).
Exit.

For container orchestrators, set terminationGracePeriodSeconds: 60 to match.

Health checks

voltro start exposes two unauthenticated probe routes:

GET /internal/liveness → 200 ok — the process is up at all (restart the pod if it stops answering).
GET /internal/readiness → 200 ready once boot completes, 503 not-ready before (pulls the pod from Service endpoints until ready).

Point the Kubernetes liveness probe at /internal/liveness and the readiness probe at /internal/readiness.

Multi-instance + sticky sessions

For WebSocket connections to land on the same backend (required for in-process subscription state):

Reverse proxy: lb_policy ip_hash (Caddy) / ip_hash (nginx).
Cross-instance subscription invalidation is built in on Postgres (LISTEN/NOTIFY) and MySQL/MariaDB (binlog CDC); on any other dialect add @voltro/plugin-broadcast (Redis/NATS). With that in place a reconnect may land on any replica and still sees every change — sticky sessions then only keep one live connection pinned, they are not a correctness requirement.

`voltro build api --target <swift|kotlin>` — native SDK generation

Generate a fully native mobile client from the same API bindings the TypeScript client is generated from. No hand-written models, no drift: the SDK is derived from your app's capability manifest — the exact procedure descriptors + JSON Schemas the framework already assembles from source — so every type stays in lockstep with the server.

voltro build api --target swift    apps/acme/api    # → apps/acme/api/sdk/swift  (Swift Package)
voltro build api --target kotlin   apps/acme/api    # → apps/acme/api/sdk/kotlin (Kotlin Multiplatform)
voltro build api --target swift --out ./ios/Sdk --name AcmeClient .

Flags:

--target swift | kotlin — the language to emit. Required.
--out <dir> — output directory. Default: <appDir>/sdk/<target>.
--name <PackageName> — the Swift package / Kotlin module name (PascalCase). Default VoltroClient.
--kotlin-package <dotted> — Kotlin source package. Default com.voltro.client.

What each package contains:

Piece	Swift	Kotlin
Type-safe models	`Codable` structs + `String` enums	`@Serializable` data classes + enum classes
One-shot client (query / mutation / action)	`async throws` methods over `URLSession`	`suspend` methods over Ktor
Subscription client (streams)	`AsyncThrowingStream` over `URLSessionWebSocketTask`	`Flow` over Ktor WebSockets
Auth + tenant context	`AuthContext` (bearer + `x-tenant` headers)	`AuthContext`
Push registration	`PushRegistration` stub	`PushRegistration` stub

Type mapping is faithful: string → String, integer → Int, number → Double/Double, boolean → Bool/Boolean, arrays → [T] / List<T>, nested objects → their own named type, string-literal unions → an enum, and an optional field (one absent from the schema's required set, or a NullOr) becomes a Swift Optional / Kotlin nullable with a = nil / = null default.

Scope — this is the SDK code generator, not a native runtime. Deliberately out of scope (they need a native runtime or managed infra, not generated client code): native module bindings (camera, biometrics), the APNs/FCM push sender (per-tenant Apple/Firebase credentials, provisioned server-side), and the managed OTA / EAS build pipeline. The generated source is verified at the generator level (golden-string tests over the emitted Swift + Kotlin). Compiling it with swiftc / Gradle is the remaining step in your own mobile CI — the framework harness has no Swift/Kotlin toolchain.

Serving: asset prefix, pre-compression, sourcemaps, keep-alive

Four knobs that decide what leaves the container. All are voltro start concerns; none change what your code does.

// apps/web/app.config.ts
web: {
  // Serve `assets/` from a CDN. Becomes vite's `base`, so every emitted URL —
  // entry, modulepreloads, CSS, images, fonts — is written with the prefix at
  // BUILD time. Pre-rendered HTML still comes from the app; upload
  // `dist/assets/` to the prefix on deploy. Filenames are content-hashed, so a
  // previous deploy's assets stay valid for a visitor mid-navigation.
  assetPrefix: 'https://cdn.example.com/_assets',

  // Emit `.map` files WITHOUT a `//# sourceMappingURL` comment, so nothing in
  // the shipped JS points at them. For `plugin-sentry`: upload them in your
  // deploy step and DELETE them before the image is built. `voltro start`
  // refuses to serve a `.map` regardless, so a forgotten delete is not a leak.
  sourcemaps: 'hidden',
},
http: {
  // Node hangs up an idle keep-alive connection after 5s; every proxy in front
  // holds one longer, and the request that lands in that window comes back as
  // a 502. Default 72000 clears nginx-60/ALB-60; raise it above YOUR proxy's
  // idle timeout. `headersTimeoutMs` must exceed it and is derived if omitted.
  keepAliveTimeoutMs: 72_000,
},

Pre-compression is automatic. voltro build writes .br (quality 11) and .gz beside every content-hashed asset over 1 KB, and voltro start serves the variant when the client accepts it. Measured on one 321 KB chunk, three requests:

	time	bytes
compressed per request (before)	5.6 / 5.0 / 4.6 ms	100 665
pre-compressed (now)	1.6 / 1.7 ms	86 083

Faster and smaller: a build can afford brotli q11 where a per-request path cannot. Both encodings of one asset carry the same ETag — it is computed over the uncompressed file, so a shared cache sees one representation.

A cross-origin api gets a preconnect. When an api's wsUrl is on another host, the shell carries <link rel="preconnect" href="…" crossorigin> so DNS + TCP + TLS overlap the bundle download instead of following it. Same-origin apis are skipped — the browser already has that connection.

`voltro serve <appDir>` — API apps only

voltro serve is the production server for an API app. On a web app it refuses and points you at voltro start:

`voltro serve` is the production server for an API app — this is a WEB app.

  production   voltro start .
  development  voltro dev .

That is a refusal, not a missing feature. serve used to build a web app a second time and hand it to vite preview, and both halves were wrong:

In production it never ran. The launcher's serve fast path requires .framework/dist-api/serveBundle/serveEntry.js — an artefact a web build does not produce — so a web app exited 1 pointing at a path that cannot exist, directly after a voltro build that had just succeeded.
Below production it destroyed the build. That second build had no @tailwindcss/vite, no image pipeline and no per-page islands entries. With Tailwind it aborted; without it, it succeeded — and since both builds write .framework/dist, which Vite empties, it deleted dist/server, the island shells and every pre-rendered page. voltro start could then not boot at all.

So the table is:

app	development	production
web	`voltro dev`	`voltro start`
api	`voltro dev`	`voltro serve`

`voltro doctor` — preflight a production serve

Production voltro serve for an API app boots ONLY from the precompiled serve bundle and is fatal if it's missing — a hand-rolled Dockerfile that runs voltro serve without a prior voltro build breaks at deploy. voltro doctor (or voltro serve --preflight) catches that at BUILD time instead of cold-start:

voltro doctor .                 # check the serve bundle exists; print the fix if not
voltro serve --preflight .      # same check, then exit — never boots

It exits 1 when the serve bundle is missing on an API app (so it fails a CI / Docker step) and prints the exact remedy: add a voltro build . step before voltro serve .. Drop it into your image build right after voltro build to guarantee the artefact is present before the image ships.

Relations a query loads but does not declare

An eager-loaded relation is part of the RESULT, so its table has to be in source: or the view stops updating when it changes:

✗  1 query loads a relation it does not declare:
   tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare
   'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes.

This is the failure that looks like a broken feature and is not: the write lands, a reload shows it, and every test of the write path is green. The name in source: is spelled right and the table exists, so neither the typed source: nor the boot audit has anything to say.

The rule has no exception list, deliberately. It resolves .with({ … }) keys through the relation registry, so the missing table is a fact rather than an inference — and a many-to-many is reported twice when needed, because the junction table is where a link add/remove actually writes.

It reads what it can read literally: a computed .with() key yields nothing rather than a guess.

The access-decision gate

Before the authz scan below — which is a heuristic over executor SOURCE — doctor runs the same gate the boot runs: every wire-exposed procedure must declare guards: or openAccess:. It is not advisory and not a ratchet, because a green answer here means the app starts:

access decisions · security.defaultDeny ON
  ✗ no access decision                       3
  ✓ openAccess, declared on purpose          2
      pricing.current — public pricing page, reads no caller data
      status.ping — health probe

  ✗ invoices.list  (query)
      src/api/invoices.query.ts

Every undecided procedure is listed — never a prefix — and the same set is in voltro doctor --json under accessDecisions for a CI gate:

voltro doctor --json | jq '.accessDecisions.undecided[] | {tag, kind, file}'

An app that sets security: { defaultDeny: false } still gets the list, marked advisory, and doctor does not fail on it. Detail: Authorization.

The authz scan

voltro doctor answers one mechanical question over every executor: does it reference an access check at all?

authz scan · 586 executor(s)
  ✗ no access check                          21
  ⚠ inline ownership check, no named guard   24   (informational)
  ✓ guards: on the descriptor                 0
  ✓ calls a guard from the vocabulary       320
  – accepted as recorded debt               221   (voltro-authz-allowlist.txt)

  ✗ teams.deleteSubTeam  — deletes teams with nothing constraining WHICH row
      api/teams/deleteSubTeam.mutation.server.ts

It scans queries and streams too, not only writes: an executor that takes an id and returns the row is the same hole as one that writes it. The exploitable shape is "acts on a row the client named, without comparing anything on that row to the caller", and a read has it.

It learns your guard names. An exported require* / assert* from your own source counts as a guard, so requireTeamAccess() is recognised without any configuration. Without that the scan would report every call site of your own guards, which is the failure mode that makes a check ignorable.

It reads your whole source tree for those names, not just the convention-named files — guards live in lib/access.ts, not in *.mutation.ts. The line above the counts tells you what it found, and it is worth reading before you trust the numbers:

  guard vocabulary: 17 from your source (requireTeamAccess, assertInquiryAccess, …)

If it instead says framework names only — no exported require*/assert* found in this app while you know you export some, the counts below it are not meaningful: every call site of your own guards is being reported as unguarded. Check that they are exported and that the name starts with require / assert followed by a capital.

An inline ownership check is informational. row.userId !== subject.id → new AccessDeniedError({}) is correct code — it is listed so you can see where the rule lives in a handler rather than on a descriptor, and it never fails the run.

Findings are ordered by blast radius: a delete outranks an insert, and a target table that is tenant()-scoped or referenced by other tables outranks one that is neither.

The ratchet — how to adopt this on an existing app

A first run on a large app reports hundreds of handlers, and nobody triages hundreds of findings. So record them once and fail only on what comes after:

voltro doctor --write-authz-allowlist    # writes voltro-authz-allowlist.txt
voltro doctor                            # exits 1 on anything NEW

The file is debt, not approval — every line is a handler nobody has confirmed is safe. It is keyed by rpc tag rather than path, so moving a file can neither re-open a hole nor hide one, and it is consulted last: an executor that gains a real guard is reported as guarded whether or not its line is still there. The list can only shrink unless someone adds to it deliberately.

Two kinds of line, because "debt" and "reviewed" are different claims. A bare tag is debt. A tag with reviewed=<why> says a human read the executor and found it genuinely open — constrained by something the scanner cannot see:

teams.deleteSubTeam
inquiries.publicFeed  reviewed=public by design; returns only published rows

The reason is required: reviewed= with no why is the claim without the evidence, and doctor refuses it. A bare tag is always available and is the honest alternative. The two are counted and printed apart, and --write-authz-allowlist is additive: it keeps the existing file verbatim — entries, comments, grouping, order — and appends only tags it does not already contain. It cannot remove a line. Removing one is your edit, or it happens on its own when an executor gains a guard and its line stops mattering.

Reading the whole list

The human view prints the 20 most severe unchecked executors. The complete scan — every finding, the counts, the inferred guard vocabulary, and the debt/reviewed split — is in voltro doctor --json under authz:

voltro doctor --json | jq '.authz.unchecked[] | {tag, why, path}'

Nothing is truncated there. If you are triaging, work from the JSON.

Before you hand-roll another check

If your checks are imperative because a scope cannot express "may this subject act on THIS row", that is what guards: [{ action, resourceType, resource }] is for — and an app whose relationships live in its own tables (a teamMembers row, say) registers its own tuple source instead of copying data into a framework table. See Authorization.

The predicate-column check

eq / isNull / inSet are free functions, so the column name arrives as a bare string and the builder cannot relate it to the table the predicate is attached to:

database.teamAppointments.where(isNull('deletedAt'))
//                               ^ teamAppointments has no softDelete() mixin,
//                                 so no `deletedAt` column exists. tsc: OK.

That type-checks — review and CI pass — and then fails at runtime as a bare SQL error. voltro doctor checks every literal predicate column against the table's declared columns and names both:

✗  predicate columns: 1 filter on a column that does not exist (214 checked)
  api/appointments/rollforward.query.server.ts:31  'teamAppointments' has no column 'deletedAt'
    columns: id, teamId, startsAt, createdAt, updatedAt
  This type-checks today and fails at runtime as a bare SQL error.

Matching is on the AST, never on text, so a column name in a comment or an unrelated string cannot trip it. A call site whose table cannot be resolved is skipped silently — an unresolvable receiver is usually not a table at all.

The type-level fix (binding the predicate to the row, where(c => isNull(c.x))) is the right end state and is planned separately. This check is the half that works retroactively: it finds the bug in code that already exists, which a type change never will.

The detector also flags raw fetch() in server files. The SSRF guard the framework ships lives in the HttpClient handlers yield* — so it protects exactly the apps that already adopted it, and misses the ones that never did. Those are usually the same apps that secured least elsewhere, which is why the absence is worth naming out loud rather than assuming the default did its job.

The rule follows the IMPORT GRAPH, not the filename. Server-convention files (*.server.ts, *.cron.ts, *.subscribe.ts, …) are the starting points, and any file reachable from them and from nothing else counts as server code too. That matters: keyed on filenames alone the rule caught 9 of 39 outbound calls on the app that reported it — the other 30 sat in lib/*.ts helpers (payments, an AI provider, TTS) imported only from server executors. A lib/payments-mollie.ts is not client code, and no file extension can say so.

A helper a page ALSO imports stays unflagged, and that is the property keeping this rule useful: fetch is unremarkable in a browser component, and flagging it there would make the rule noise that gets scrolled past — taking the real findings with it. Relative imports and your tsconfig paths aliases are both followed.

The detector also flags an executor that never names its own descriptor. Pairing is by FILENAME, which is right — and it means a *.server.ts can be a complete, correct executor with no reference at all to the contract it implements. Those are exactly the files where a hand-written input drifts from the wire: in one reported codebase, six executors declared boardPurpose: string where their own descriptor said Schema.Literal(...), discarding the contract at the executor boundary. Fix by importing the descriptor and typing the input as ExecutorInput<typeof descriptor>. Only a SIBLING import clears the finding — an executor importing nothing but @voltro/* and node:* has still not named its contract.

The `workflows.start` audit

voltro doctor also diffs every workflows.start(name, payload) call site against the workflows the app actually registers:

✗  workflow starts: 13/14 call sites checked
  api/crons/weekly.cron.ts:22  'sprint.report' payload is missing: teamId
  api/crons/weekly.cron.ts:22  'sprint.report' payload has unknown field(s): scheduledAt
    accepted: sinceIso, teamId
  1 UNCHECKED (not verified — not a pass):
    api/crons/digest.cron.ts:8 — payload spreads a value

Why this exists even though workflows.start validates at runtime. Runtime validation fires on the next firing — which for a daily cron is hours, for a weekly one is a week, and for a quarterly one is a quarter. And voltro inspect schedules --failing cannot see a job that has never fired, because its roll-up is built from recorded runs. A weekly workflow broken by a refactor is invisible to both until it next runs.

UNCHECKED is never folded into a pass. A payload built with a spread or a computed key can contribute any name, so its key set is unknowable here. Those call sites are counted and listed rather than passed silently — 0 issues must not be readable as "all verified". The workflow name is checked regardless, since a rename or a deletion is decidable whatever the payload looks like.

The required keys come from the live payloadSchema, the same source the runtime validation reads, so the two cannot disagree about what a payload needs.

The junction-FK check

A link / junction table (projectMembers, todoTagAssignments) exists to connect two aggregates, so its columns are almost all foreign keys. Declared with reference(() => projects) the framework knows the edge — it enforces integrity, auto-indexes the FK, and can walk the reference graph. Declared as a bare text() id column the same edge is invisible: no FK, no auto-index, and nothing that walks references can follow it. Nothing type-checks the difference.

voltro doctor flags a junction table with an id-shaped column that is a plain scalar and not a reference():

junction FKs: 2 junction tables with an id column that is a plain text() and not a reference()
  'todoListMembers': 'todoListId', 'userId' (part of a composite primary key)
  'todoTagAssignments': 'todoId', 'tagId' (this table is nothing but link columns)
  Declare each as reference(() => <table>): the FK is enforced, the column is auto-indexed,
  and the relationship becomes walkable (a plain text() id column is an invisible edge).

It will not fire on any *Id text column — a tenantId, a traceId, an external-system reference are all legitimate plain-scalar shapes. It fires only when the table's OWN structure independently says "link table", and it names which signal tripped it so the finding is auditable rather than a bare accusation:

Signal	What it means
`part of a composite primary key`	the suspect column is a member of an explicit `primaryKey([...])` — the PK structure alone proves the row is a link
`sits beside a wired reference() on this table`	a real `reference()` on a same-shaped sibling column, while this one is a bare scalar
`this table is nothing but link columns`	the whole table is id-shaped columns + bookkeeping (a pure link table)

The audit reads the tables' real declared ColumnTypes — the same materialised column definitions the migrator emits DDL from — never source text. So a reference is told apart from a plain scalar by its declared type, not a name regex, and a column name that only appears in a comment cannot trip it.

Event delivery + scale

Two events with identical route / subscriber / buffer numbers can mean opposite things about a missing message — each counts a drop as a loss and tells the subscriber, latest supersedes the pending value and says nothing — and that mode is invisible once the app is running. So voltro doctor lists every declared event's delivery mode:

event delivery: 4 declared events — the mode decides what a MISSING message means
  'games.started': each
  'player.moved': latest
  each   — every delivery matters; a slow subscriber loses the oldest and is TOLD how many (the default).
  latest — a newer delivery supersedes a pending one; a slow subscriber gets the current value, told nothing.

It also warns on two shapes that will not scale the way the declaration reads — advisory, never blocking:

Warning	Why
routing key has 3+ fields	every key field is a routing address, and the count of distinct routes is the product of the fields' value spaces. Check each is an ADDRESS the delivery is decided by (`arenaId`), not a discriminator the handler reads (`gameType`) — the latter belongs in the payload, not the key.
`webhook:` on a per-frame event	a webhook block on a name like `player.moved` / `cursor.moved` / `.frameRendered` becomes N HTTP deliveries per second per subscribed target. The webhook rate limit defers* the excess as pending rows rather than failing, so the symptom is a growing table. Publish a coarser event (a summary / state change) for the outside world.

The field count comes from the same schema-property reader the runtime validation uses, so it cannot disagree with the key the event actually routes on. Both findings appear in voltro doctor --json under eventDelivery.

The hand-roll detector

voltro doctor also scans your source for shapes the framework already has a primitive for, and names the primitive at the spot the hand-roll lives. This is advisory and never blocking — it prints, it does not fail your build.

voltro doctor .

•  Shipped primitives you may be hand-rolling:
   [server]
   hand-written not-found branch on rows[0] — 12 file(s): queries/team.get.ts, …
     → .one() — fails with the typed NoRowFound on zero rows AND on more than one
   [client]
   per-field useState + a submit flag (hand-rolled form) — 4 file(s): src/create-dialog.tsx, …
     → useFormBinding — fields + validation from the mutation input Schema

It covers both halves of the stack:

Scope	It notices	Reach for
server	`if (!rows[0]) throw …`	`.one()` / `.first()`
server	3+ sequential `store.query` in one handler	`relations()` + `.with()` — or `Effect.all`
server	`Effect.promise(() => ctx.store.…)`	`yield* EffectStore`
server	`requireScope(...)` at the top of an executor	`guards:` on the descriptor
server	a `token` / `secret` / `password` column with no encryption	`.encrypted()`
server	a notify / webhook helper called at a mutation's tail	`defineSubscriber` / `defineReaction`
server	a `*.subscribe.ts` handler that writes or publishes, with no `once:`	`once: true` on `defineSubscriber`
server	an executor builds a field its descriptor's `output` does not declare	add it to `output` — the struct IS the serializer
server	a mutation writes a NULLABLE column through an input field that cannot be `null`	`Schema.optional(Schema.NullOr(...))`
server	`hasMore` + `limit + 1`	`paginateById`
server	`.getTime()` / `.toISOString()` mapping a row on the way out	`timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct
client	per-field `useState` + a submit flag	`useFormBinding`
client	a table with local sort/filter state	`useDataTable`
client	`FileReader` / `readAsDataURL`	`useUpload`
client	`setTimeout` debounce in a `useEffect`	`useDebounced`
client	`useMemo` fanning in several subscriptions	`useDerived`
client	a local Next.js compat shim	the native `@voltro/web` exports
client	a hand-rolled presence heartbeat	`@voltro/plugin-presence`
client	`data === undefined` / `!data` on a subscription result	branch on `loading` (and `idle`, if you pass `skip`)

The subscription rule resolves the binding rather than matching text, and that distinction is the reason this scanner parses at all. A deployment migrating these call sites wrote a regex codemod for the same job, and it rewrote a summary === undefined check inside a child component where summary was a PROP. Their compiler happened to catch it, because that name was out of scope there; had the names matched, a silent behaviour change would have shipped. Text cannot tell you which declaration an identifier refers to — so a rule about identifiers has no business being written in text.

The rules are deliberately conservative — a detector that cries wolf trains you to ignore it. A column that already carries .encrypted(), or a handler that already uses .one(), stays silent.

Two of them are worth spelling out, because their advice is not one-line:

The subscriber rule is the second half of the mutation-tail rule. That one moves an effect OUT of a mutation and into a subscriber, which is right — and lands it on a channel every replica listens to. store.onChange is a broadcast: correct for a READER (a cache drop, an index refresh, a live query must run everywhere) and a multiplier for an EFFECT, because there is nothing to make idempotent — the effect IS the write, so each run produces another one. One INSERT behind two replicas therefore writes two notification rows, and four with a broadcast bus in front.

So the rule fires when a handler WRITES (ctx.store.insert / update / upsert / …), publishes (ctx.publish), or calls a notify / sendWebhook / sendMail-shaped helper, and the subscriber declares no once:. Any once: silences it — true or a key function — because the question is whether the decision was made, not which way. It reads the handler through the AST, so handler: notifyApprovers naming a function in the same file is judged exactly like an inline arrow; a handler IMPORTED from another module is not judged at all, since its body is not in the file being read.

Two rules read a DECLARATION against a DECLARATION, and are therefore exact. executor-builds-an-undeclared-field compares the object literal an executor returns with its descriptor's output struct: since the struct IS the serializer, a key it does not declare is stripped on the way out, so every reader downstream gets undefined and renders a blank with nothing logged anywhere. nullable-column-a-mutation-cannot-clear compares a mutation's target table's nullable columns with its input schema — a nullable column written through a field that cannot be null can be set once and never emptied.

Both REFUSE rather than guess, and the refusals are the interesting part. A spread on either side of the output comparison ({ ...row, extra }, or a ...Base inside the declared struct) means the key set is not knowable from the source; reporting the visible half would name the field the author can already see and miss the ones they cannot. An output that is a named schema rather than a literal struct is unjudgeable, not empty — the second reading would make every field a finding. And a table declaration the scan cannot find produces no finding at all, because "this table has no nullable columns" and "I could not look" lead to opposite conclusions.

It stays quiet on a reader on purpose. once: on a cache-warming subscriber would silence it on every replica but one, which is worse than the repetition it removes — only the handler's author knows which of the two they wrote.

The credential-column rule skips names that aren't credentials. A name ending in Id / _id, a name ending in Hash / _hash, and a name beginning with vault are all left alone:

Column	Why it's skipped
`jiraSecretId`, `token_id`	an IDENTIFIER of a secret held elsewhere, not the secret
`apiKeyHash`, `password_hash`	the hash IS the protection — encrypting it is nonsense, and it breaks the column as a unique lookup key
`vaultToken`	a HANDLE into a secret store, naming a secret held elsewhere

The suffix tests use a camelCase / underscore boundary on purpose: a blind /id$/i would also swallow apiKeyValid, while tokenIdentifier — which ends in neither — must still fire.

The sequential-reads rule names TWO levers, and the criterion for choosing. Both shapes chain later reads off earlier results, so no text-level heuristic can split them — you make the call:

The reads are a parent → child walk on ONE key → declare relations() in a *.relations.ts and collapse them into .with({ … }): one JSON-aggregate query, on every dialect.
The reads collect ids from SEVERAL sources (JSON-array references, a junction carrying extra columns, JS-side sorting) → keep the assembly and run the independent LEADING reads under Effect.all. Same queries, same results, only concurrent — zero parity risk.

The second case is the common one. Measured on a real 74-hit codebase, about two handlers were clean full-parity relations() conversions and the other ~72 were multi-source assemblies where .with() covers only part of the work or subtly changes behaviour. Prescribing relations() for all of them would be wrong ~97% of the time — and advice that is usually wrong trains you to ignore the finding.

The human view shows the first three file paths per finding and says how many it withheld. Those paths are the actionable part — a count you cannot turn back into a work list tells you the size of the problem, not how to fix it — and the matching rule lives inside the CLI, so you cannot re-derive the list with your own grep. --json prints the complete scan, nothing elided, with no preflight output mixed in:

Unimported `@voltro/*` dependencies

A declared framework dependency nobody imports still gets installed, walked on every voltro update, and read as evidence the package is in use — its breaking-change notes included. The usual origin is a migration: the app moves off a framework package to a third-party one, and the package.json entry stays. voltro doctor checks every @voltro/* in dependencies and devDependencies for an import site:

unimported deps · 8 @voltro/* package(s) declared, 214 file(s) scanned
  ⚠ @voltro/i18n — declared in dependencies, imported nowhere
      a dependency nobody imports still gets installed, updated, and read as
      evidence the package is in use — its breaking-change notes included.
      Remove it, or if it IS imported through an assembled specifier the scan
      cannot see, keep it and ignore this line — the rule is advisory.
  · (2 loaded by the framework itself: @voltro/cli, @voltro/sql-postgres)

Scoped to @voltro/* deliberately: for third-party packages the same question has a long tail of legitimate no-import shapes, and a rule that is sometimes wrong is one people stop reading. Three states are distinguished, and each is printed:

Exempt, by name — packages the framework loads on your declaration (@voltro/cli is the binary; @voltro/devtools is mounted by voltro dev; the @voltro/sql-* dialect drivers are loaded from your config). An exemption you cannot see is a finding you cannot question.
Not measurable yet — @voltro/client / @voltro/web are normally imported by generated code. On a tree where codegen has never run, their absence is a missing measurement, not a dead dependency; the section says so and tells you to run voltro dev once.
Unimported — advisory, never fatal. A mention in a comment or an error string does not count as an import (a commented-out import is exactly the residue this looks for), and an import assembled at runtime from string pieces is invisible to the scan — the finding text says both.

The full report is in voltro doctor --json under unimportedDeps (null when there is no package.json to read — "could not check" and "checked, clean" never print the same).

Duplicate package instances

voltro doctor also reports any identity-sensitive package resolved at more than one version — effect, @effect/*, @voltro/*, react/react-dom:

•  1 package(s) resolved at more than one version:
     effect — 3.18.4, 3.21.0
       node_modules/effect
       ../../node_modules/effect

This is worth its own check because of how it PRESENTS. Effect's types are nominal, so a Schema built by one copy is not the type the other expects, and the errors land in the GENERATED rpcGroup.generated.ts — a file you cannot edit and did not write:

Property '[TypeId]' is missing in type … Schema<any, any, unknown>
Type 'typeof Never' is not assignable to type 'All'
Argument of type 'Rpc<…, Stream<…>, …>' is not assignable to 'Any'

Read cold, that says "the framework emits bad types". It says nothing about the dependency tree, which is where the problem is. And the RUNTIME usually stays green — two instances only diverge where identity matters — so the app boots, serves and passes its tests while tsc is red.

Fix it in the install, not the code: align the version across the workspace (a root pnpm.overrides / resolutions entry for effect is the blunt instrument), then reinstall. Do NOT add @ts-nocheck to the generated file — it is exactly where a genuine mistake in your own descriptors surfaces.

voltro doctor . --json          # the complete scan: every file path, machine-readable

{
  "root": "/app/api",
  "scannedFiles": 214,
  "scannedDirs": ["queries", "mutations", "database"],
  "findings": [
    {
      "id": "row-not-found",
      "scope": "server",
      "smell": "hand-written not-found branch on rows[0]",
      "use": ".one() — fails with the typed NoRowFound on zero rows AND on more than one",
      "files": ["queries/team.get.ts", "queries/user.get.ts", "…"]
    }
  ],
  "spaCandidates": []
}

That is the form to hand an agent, or to pipe into a script that works the list file by file.

`renderMode:'spa'` candidates

voltro doctor also flags web pages that could adopt renderMode: 'spa' without losing their server-rendered shell. A page under a layout renders that LAYOUT chain on the server — nav, sidebar, auth gate, via the layout's own loader — even when the page itself is 'spa'. So a page whose BODY needs no SSR can skip its per-page SSR compile while the shell still server-renders. Like the hand-roll detector, this is advisory and never blocking.

A page is listed when ALL of these hold:

it is a page file — not layout.tsx / loading.tsx / error.tsx / not-found.tsx;
it exports no loader (so 'spa' loses nothing the page contributed server-side);
its renderMode is 'ssr' or unset/default — not a page that already opted into a non-SSR render ('spa' / 'static' / 'isr', or any other explicit mode);
a layout.tsx sits somewhere in its directory chain — root, an ancestor, or the page's own dir. This is the load-bearing condition: only then does a layout still SSR the shell. A page with no layout would, as 'spa', ship no server HTML at all — so it is never flagged.

•  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
   src/pages/dashboard/page.tsx  (/dashboard) — default renderMode
   src/pages/admin/settings/page.tsx  (/admin/settings) — renderMode:'ssr'
     → renderMode:'spa' skips this page's SSR compile while its layout shell still renders server-side — adopt it if the page BODY does not need SSR (internal/authenticated pages); keep 'ssr' if the page content needs SEO or server first-paint.

Adopt 'spa' for internal or authenticated pages whose content needs no SEO or server first-paint; keep 'ssr' (or the 'static' default) when it does. There is deliberately no codemod to flip pages automatically — dropping a page body's server render is a per-page product decision, not a mechanically-safe transform. Every candidate (with its file, pattern, and currentMode) is also in voltro doctor --json under a spaCandidates array; the human view above caps at ten pages and points to --json for the rest.

`voltro capabilities` — what the framework actually exports

Asked "what does this framework export", a language model will produce a confident answer whether or not it knows. This command replaces that guess with a reading of the .d.ts files in your own node_modules:

voltro capabilities              # human summary, grouped by package
voltro capabilities --json       # the full machine-readable surface

voltro capabilities — 3856 exported symbols across 36 packages
  @voltro/runtime@0.38.0 — 12 primitives, 5 hooks, 100 components, 360 values, 388 types
    defineAggregate, defineConnection, defineCostBudget, defineEventTrigger, defineExecutor, …
  @voltro/database@0.38.0 — 3 primitives, 33 components, 333 values, 223 types
    defineMigration *, defineMixin, defineSeed *

  * 9 primitive(s)/hook(s) appear nowhere in this project's agent guide:
      @voltro/database: defineMigration
      @voltro/plugin-flags: defineFlag
      …

The count is the packages installed in that project, not everything the framework publishes — a leaner app reports fewer.

Every symbol reported was read out of an installed package a moment ago, so an agent can verify the surface instead of recalling it. The --json form is stable and locale-independent — the same tree produces byte-identical output on every machine, so you can diff it across upgrades.

Symbols marked * ship but appear nowhere in this project's seeded AGENTS.md / CLAUDE.md. Refresh the guide with voltro agents-md --force, or read that package's README.

Anti-patterns

Running voltro start against a directory without dist/. It exits 1 with a clear no built dist found — run voltro build first (checked against .framework/dist/index.html before any heavy work). Run voltro build first.
voltro start in dev to "test prod". Use voltro build && voltro start. The dev server has different behaviour; serving dev artefacts via start is undefined.
Skipping the SSR bundle build. Middleware mode is slower (cold-start cost on every render). For production deploys with renderMode: 'ssr' pages, build the bundle.

Build & start

#voltro build <appDir>

#Output layout

#Unresolvable optional peers

#voltro start <appDir>

#Flags + env vars

#Per-request routing logic

#ISR cache backends

#Tenant-aware ISR

#CDC invalidation

#Graceful shutdown

#Health checks

#Multi-instance + sticky sessions

#voltro build api --target <swift|kotlin> — native SDK generation

#Serving: asset prefix, pre-compression, sourcemaps, keep-alive

#voltro serve <appDir> — API apps only

#voltro doctor — preflight a production serve

#Relations a query loads but does not declare

#The access-decision gate

#The authz scan

#The ratchet — how to adopt this on an existing app

#Reading the whole list

#Before you hand-roll another check

#The predicate-column check

#The workflows.start audit

#The junction-FK check

#Event delivery + scale

#The hand-roll detector

#Unimported @voltro/* dependencies

#Duplicate package instances

#renderMode:'spa' candidates

#voltro capabilities — what the framework actually exports

#Anti-patterns

#See also