@voltro/cli 0.5.0 → 0.6.0

package/templates/agent-docs/data.md

@@ -193,9 +193,9 @@ Save both files and `notes.list` becomes a streaming query in the typed client.
 import { useSubscription } from '@voltro/client'
 
 export default function Notes() {
-  const { data, error } = useSubscription('app', 'notes.list', {})
+  const { data, loading, error } = useSubscription('app', 'notes.list', {})
   if (error) return <p>Error: {String(error)}</p>
-  if (data === undefined) return <p>Loading...</p>
+  if (loading) return <p>Loading...</p>
   return (
     <ul>
       {data.map((note) => <li key={note.id}>{note.title}</li>)}
@@ -304,6 +304,108 @@ defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' },
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
 
+## `output` is the serializer — `rowSchema(table)`
+
+A descriptor's `output` is not documentation of the shape. It **is** the
+serializer: it is handed to the rpc as the success schema, so a handler's result
+is *encoded through it* on the way out and decoded on the client. Any conversion
+the schema describes, the framework performs — you never need a converter at the
+tail of a handler.
+
+That is worth stating plainly, because the symptom is usually read backwards.
+A `timestamp()` column comes back from the store as a `Date`, and `Date` is not
+JSON. Declaring that field as `Schema.Number` looks like the fix, but it
+describes the **wire** type rather than the domain type — which leaves the schema
+with nothing to convert, and pushes the conversion back into the handler:
+
+```ts no-check
+// The shape that leads to hand-written converters everywhere
+output: Schema.Array(Schema.Struct({ createdAt: Schema.Number })),
+// …and then, at the tail of every executor:
+return rows.map((row) => ({ ...row, createdAt: row.createdAt.getTime() }))
+```
+
+Declaring `Schema.DateFromNumber` instead makes the conversion automatic — but
+nobody wants to hand-map thirty columns to work that out per table.
+`rowSchema(table)` derives the whole struct from the table definition:
+
+```ts
+// apps/api/queries/notes.list.query.ts
+import { defineQuery } from '@voltro/protocol'
+import { rowSchema } from '@voltro/database'
+import { Schema } from 'effect'
+import { notes } from '../database/schema'
+
+export const listNotes = defineQuery({
+  name:   'notes.list',
+  source: 'notes',
+  input:  Schema.Struct({}),
+  output: Schema.Array(rowSchema(notes)),
+})
+```
+
+The executor returns rows straight from the store. No converters:
+
+```ts no-check
+// apps/api/queries/notes.list.query.server.ts
+export default () => database.notes.orderBy('createdAt', 'desc').limit(100)
+```
+
+### The Encoded / Type split
+
+That split is the whole point — the handler works in domain types, the wire
+carries something JSON can represent:
+
+| Column | In the handler (Type) | On the wire (Encoded) |
+|---|---|---|
+| `timestamp()`, `date()` | `Date` | `number` (epoch ms) |
+| `bigint()` | `bigint` | `string` (decimal) |
+| `text()`, `enum()`, `id()`, `reference()` | `string` | `string` |
+| `integer()`, `real()`, `decimal()` | `number` | `number` |
+| `boolean()` | `boolean` | `boolean` |
+| `json()`, `vector()`, `raw()` | `unknown` | `unknown` |
+
+`bigint()` crosses as a **decimal string** on purpose: a `bigint` sent as a JSON
+number rounds silently past 2^53, and a value that is quietly wrong is worse than
+one that is rejected.
+
+`json()` / `vector()` / `raw()` map to `Schema.Unknown` rather than a guess.
+These are shapes the column declaration does not pin down, and a schema that
+guesses **wrong** rejects valid rows at the wire boundary — reporting the failure
+far from the column responsible. Loose beats wrong here; declare the precise
+shape yourself when you want one.
+
+A `.nullable()` column wraps its mapped type, so a null timestamp round-trips as
+`null` rather than becoming epoch 0 (which would render as a plausible
+`1970-01-01` instead of "never").
+
+### Keeping a column off the wire — `omit`
+
+```ts
+import { rowSchema } from '@voltro/database'
+import { users } from '../database/schema'
+
+rowSchema(users, { omit: ['passwordHash'] })
+```
+
+`omit` is a **convenience, not a security boundary**. The column is simply absent
+from *this* schema; a handler that returns the same row under a different schema
+still sends it. For a real boundary, see
+[`.encrypted()` and column sensitivity](/docs/database/sensitivity).
+
+### One column at a time — `columnSchema`
+
+`columnSchema` maps a single column, and it takes a column **definition** — what
+`table.fields` holds — not the builder that `text()` or `timestamp()` returns
+(a builder's definition is private, so it cannot be read from outside):
+
+```ts no-check
+import { columnSchema } from '@voltro/database'
+
+columnSchema(notes.fields.createdAt)   // ✅ a definition, from table.fields
+columnSchema(timestamp())              // ❌ a builder — not readable
+```
+
 ## What gets sent on the wire
 
 Queries are streaming RPCs whose elements are **subscription events**: an initial `snapshot` followed by `delta`s. See [Wire protocol](/docs/data/wire-protocol#subscription-events-snapshot-delta) for the envelope shape. For plain element streams, use [Streams](/docs/data/streams).
@@ -327,11 +429,34 @@ a flash of empty-state before the first snapshot:
 | `isEmpty` | snapshot arrived, zero rows (or a null value) | empty state |
 | neither | rows present | the list |
 
+### `loading` narrows `data`
+
+`SubscriptionState<T>` is a **discriminated union on `loading`**, so `loading` is
+not a flag sitting beside `data` — it is a type guard for it:
+
+```ts
+type SubscriptionState<T> =
+  | { loading: true;  data: undefined; isEmpty: false }
+  | { loading: false; data: T;         isEmpty: boolean }
+// both members also carry revision, emittedAt, error and pendingPatches
+```
+
+Once you have returned for `loading`, `data` is `T`. No `?? []`, no `!`:
+
 ```tsx
 const { data, loading, isEmpty } = useSubscription<Note[]>('app', 'notes.list', {})
 if (loading) return <TableSkeleton/>
 if (isEmpty) return <EmptyNotes/>
-return <NotesTable notes={data!}/>
+return <NotesTable notes={data}/>
+```
+
+A derived constant narrows just as well, as long as `loading` is part of it:
+
+```tsx
+const { data, loading } = useSubscription<Note[]>('app', 'notes.list', {})
+const isLoading = !currentUser || loading
+if (isLoading) return <TableSkeleton/>
+return <NotesTable notes={data}/>   // data is Note[]
 ```
 
 `fallback` fills `data` while loading so a page can render its real (empty) shell
@@ -342,11 +467,18 @@ const { data, loading } = useSubscription('app', 'notes.list', {}, { fallback: [
 // data is [] before the first snapshot; loading is still true
 ```
 
-**Errors.** `error` carries a **cold-start** stream failure (nothing ever
-arrived) — check it to avoid an infinite skeleton. A failure AFTER data arrived
-deliberately does NOT replace good data with an error banner (a transient
-websocket hiccup would blank a working screen); those reach the api's error bus
-instead — subscribe with `useOnRpcError` for connection-level UX.
+That call returns `SubscriptionStateWithFallback<T>` instead of the union: `data`
+is always present (the fallback stands in until the first snapshot) and `loading`
+is a plain boolean reporting the true state. There is nothing to narrow.
+
+**Errors.** `loading` means **no data has arrived yet** — it is not a claim that
+the subscription is healthy. A **cold-start** failure (nothing ever arrived)
+leaves `loading` true *and* sets `error`, so a component that branches on
+`loading` alone renders a skeleton forever; check `error` to break out of it. A
+failure AFTER data arrived deliberately does NOT replace good data with an error
+banner (a transient websocket hiccup would blank a working screen); those reach
+the api's error bus instead — subscribe with `useOnRpcError` for
+connection-level UX.
 
 
 
@@ -414,7 +546,7 @@ export default async (
 
 The descriptor is the wire contract. The `.mutation.server.ts` file is the server-only implementation.
 
-`insert` returns the post-image as an untyped `Row` (`Readonly<Record<string, unknown>>`), so narrow the field you need (`String(...)`) instead of asserting it with `as string` — an assertion silences the compiler without checking anything. To read a row back, use the fluent terminals: `ctx.store.select('notes').where('id', id).one()` fails with the typed `NoRowFound` when the row is missing (or when more than one matches), so you never need a hand-written not-found branch; `.first()` / `.maybeOne()` return `null` instead.
+`insert` returns the post-image as an untyped `Row` (`Readonly<Record<string, unknown>>`), so narrow the field you need (`String(...)`) instead of asserting it with `as string` — an assertion silences the compiler without checking anything. To read a row back, use the fluent terminals: `ctx.store.select('notes').where('id', id).one()` fails with the typed `NoRowFound` when the row is missing (or when more than one matches), so you never need a hand-written not-found branch; `.first()` / `.maybeOne()` return `null` instead. That fluent builder is string-keyed and yields an untyped `Row`; for a TYPED single row, pass the `database.<table>` builder to the store's own terminals — `await ctx.store.one(database.notes.where(eq('id', id)))` returns the row type with no cast. See [single-row terminals](/docs/database/query-builder#single-row-terminals-on-the-typed-builder).
 
 ## What The Runtime Does
 
@@ -496,6 +628,26 @@ import { setMutationNotifier } from '@voltro/client'
 setMutationNotifier({ success: (m) => toast.success(m), error: (m) => toast.error(m) })
 ```
 
+**The callback form is for SINGLE-SHOT writes.** A loop or a multi-step sequence
+relies on the promise *throwing* to stop. Once the failure is handled the promise
+resolves, so the loop cheerfully continues past the row that failed:
+
+```ts
+// WRONG — onError handles the failure, so the loop never stops
+for (const row of rows) {
+  await create.mutate(row, { onError: (e) => toast.error(messageFor(e)) })
+}
+
+// RIGHT — bare mutate rejects, so the sequence aborts where it broke
+try {
+  for (const row of rows) await create.mutate(row)
+} catch (e) {
+  toast.error(messageFor(e))
+}
+```
+
+The same applies to `run` on [actions](/docs/data/actions).
+
 
 ## Auto-Optimistic
 
@@ -736,6 +888,44 @@ const onClick = async () => {
 
 `useAction` returns `run`, `pending`, `error`, and `lastResult`.
 
+### Handling the result — `onSuccess` / `onError` / `notify`
+
+`run` takes the same options bag as a [mutation](/docs/data/mutations)'s `mutate`,
+so a one-shot action does not need a `try/catch/finally` + toast wrapper —
+`pending` already replaces the `finally`:
+
+```ts
+const invite = useAction('app', 'invites.send')
+
+await invite.run({ email }, {
+  onSuccess: (out) => toast.success(`sent ${out.id}`),
+  onError:   (e)   => toast.error(readError(e)),
+})
+```
+
+**The load-bearing rule:** supplying an error handler (`onError` **or**
+`notify.error`) marks the failure **handled** — `run` then resolves with
+`undefined` instead of rejecting, which is what removes the `try/catch`. With no
+options it rejects exactly as before, so an unhandled failure stays loud.
+
+**The callback form is for SINGLE-SHOT calls.** A loop or a multi-step sequence
+relies on the promise *throwing* to stop; once the failure is handled the promise
+resolves and the sequence runs on past the step that broke:
+
+```ts
+// WRONG — onError handles the failure, so the loop never stops
+for (const email of emails) {
+  await invite.run({ email }, { onError: (e) => toast.error(readError(e)) })
+}
+
+// RIGHT — bare run rejects, so the sequence aborts where it broke
+try {
+  for (const email of emails) await invite.run({ email })
+} catch (e) {
+  toast.error(readError(e))
+}
+```
+
 ## Action vs Mutation vs Stream
 
 | Need | Use |
@@ -1512,7 +1702,7 @@ _Per-table post-commit reactivity via file convention. Default-exported defineSu
 
 Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, emit an external notification, invalidate a cache, push to a worker queue. The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
 
-Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work, have the subscriber invoke a workflow.
+Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work — "a row changed, now run a workflow" — reach for a [reaction](/docs/data/reactions) instead.
 
 ## File shape
 
@@ -1560,22 +1750,24 @@ Subscribers are **non-durable** by design:
 - **Async handlers are NOT awaited by the dispatcher.** Fire-and-forget — a slow handler can't back-pressure the change stream. Errors propagate to the structured log via `.catch()`, but the change-emission path returns immediately.
 - **No retry, no resume.** If the process crashes mid-handler, the work is gone. Same if the network call inside the handler fails — there's no built-in retry policy.
 
-If you need any of those properties (transactional, durable, retried), invoke a workflow from inside the subscriber:
+If you need any of those properties (transactional, durable, retried), don't hand-roll the kickoff in the handler — a subscriber's `ctx` carries exactly two members (`ctx.log` and `ctx.id`), so there is no framework handle to start a workflow with. "A row changed → start a workflow" has its own primitive: a [reaction](/docs/data/reactions). A `*.reaction.tsx` watches the same post-commit change stream and its `act` starts the workflow for you, behind mandatory guards:
 
-```ts
-export default defineSubscriber({
-  table: 'orders',
-  on: 'insert',
-  handler: async (event, ctx) => {
-    // Best-effort kickoff. The workflow itself is crash-safe + retried.
-    await ctx.app.workflowClient.send('orders.fulfill', {
-      orderId: event.new!.id as string,
-    })
+```tsx
+// reactions/fulfillOrder.reaction.tsx
+import { defineReaction } from '@voltro/runtime'
+
+export default defineReaction({
+  name:  'fulfillOrder',
+  watch: { table: 'orders', on: 'insert' },
+  act:   { kind: 'workflow', workflow: 'orders.fulfill' },   // the changed row is the payload
+  guards: {
+    // REQUIRED — a stable idempotency key, so the same change acts exactly once.
+    dedupeKey: (event) => String((event.new as { id?: string })?.id ?? ''),
   },
 })
 ```
 
-The workflow body owns durability. The subscriber's job is just "translate row-change into workflow invocation".
+The workflow body owns durability; the reaction owns the trigger and the guards. `dedupeKey` is not optional — an ungated reaction whose act writes back into the watched table self-triggers forever, so `defineReaction` throws at boot when it's missing. See [Reactions](/docs/data/reactions) for the `when` predicate, `rateLimit`, `costBudgetUsd`, and the `act: { kind: 'agent' }` target.
 
 ## Why this and not a regular subscription?
 
@@ -1585,7 +1777,7 @@ A `useSubscription('app', 'todos.list')` is the right tool when the **client** w
 |---|---|
 | The browser, to show fresh data | `useSubscription` in a hook |
 | A server-side action, every commit | `*.subscribe.ts` (this) |
-| A server-side action, eventually-consistent + durable | `*.subscribe.ts` that kicks off a workflow |
+| A server-side action, eventually-consistent + durable | [`*.reaction.tsx`](/docs/data/reactions) with `act: { kind: 'workflow' }` |
 | A server-side action, in the same transaction | Do the work inside the mutation handler |
 
 ## Decision tree — picking the right seam
@@ -1596,7 +1788,7 @@ A `useSubscription('app', 'todos.list')` is the right tool when the **client** w
 | Reject the insert | [`table().validate(Schema)`](/docs/database/columns#table-level-validation) |
 | Derive a value at write time | [`column.computed(row => ...)`](/docs/database/columns#computed-columns) / [`column.default(() => ...)`](/docs/database/columns#default-with-callback) |
 | **Best-effort post-commit reactivity per row** | **`*.subscribe.ts`** (this) |
-| Crash-safe post-commit reactivity | workflow invoked from `*.subscribe.ts` |
+| Crash-safe post-commit reactivity | [`*.reaction.tsx`](/docs/data/reactions) acting on a workflow |
 | Periodically-refreshed pre-computed query | [`*.aggregate.ts`](/docs/data/aggregates) |
 | Event ingestion + analytical aggregates | [Analytics sink](/docs/plugins/analytics) |
 
@@ -1638,23 +1830,23 @@ export default defineSubscriber({
 
 ### Soft-delete cleanup workflow
 
-```ts
-export default defineSubscriber({
-  table: 'documents',
-  on:    'update',
-  handler: async (event, ctx) => {
-    // Trigger a long-running cleanup ONLY when deletedAt was just set
-    if (!event.new || !event.old) return
-    if (event.old.deletedAt === null && event.new.deletedAt !== null) {
-      await ctx.app.workflowClient.send('documents.cleanupDeleted', {
-        documentId: event.new.id as string,
-      })
-    }
-  },
+Starting a workflow off a state transition is a [reaction](/docs/data/reactions), not a subscriber — `when` expresses the transition, `dedupeKey` keeps it from acting twice:
+
+```tsx
+// reactions/cleanupDeletedDocuments.reaction.tsx
+import { defineReaction } from '@voltro/runtime'
+
+export default defineReaction({
+  name:  'cleanupDeletedDocuments',
+  watch: { table: 'documents', on: 'update' },
+  // Fire ONLY when deletedAt was just set — not on every other update.
+  when:  (event) => event.old?.['deletedAt'] === null && event.new?.['deletedAt'] != null,
+  act:   { kind: 'workflow', workflow: 'documents.cleanupDeleted' },
+  guards: { dedupeKey: (event) => String((event.new as { id?: string })?.id ?? '') },
 })
 ```
 
-The workflow does the heavy lift (scrub child rows, notify owners, archive to cold storage); the subscriber's job is just to detect the state transition.
+The workflow does the heavy lift (scrub child rows, notify owners, archive to cold storage); the reaction's job is just to detect the state transition and hand the row over.
 
 ## Failure semantics in detail
 
@@ -1663,11 +1855,11 @@ The framework logs subscriber failures via the structured logger — scope `subs
 There's no retry. If a transient failure should be retried, do one of:
 
 1. Wrap the call in your own retry policy inside the handler (`Effect.retry`, `pRetry`, etc.).
-2. Move the work to a workflow that the subscriber just kicks off — workflows have first-class retry semantics.
+2. Move the work into a [reaction](/docs/data/reactions) whose `act` starts a workflow — workflows have first-class retry semantics, and the reaction's `dedupeKey` makes the trigger idempotent.
 
 ## By design
 
-The subscriber is a deliberately thin post-commit hook — the sharp edges below are choices, not gaps. When you outgrow them, the escape hatch is a workflow (durable, retried) or handler-side logic.
+The subscriber is a deliberately thin post-commit hook — the sharp edges below are choices, not gaps. When you outgrow them, the escape hatch is a [reaction](/docs/data/reactions) acting on a workflow (durable, retried) or handler-side logic.
 
 - **One subscriber per file.** Multiple defaults exported don't compose; pick the most natural file boundary (one cohesive concern per file).
 - **Filter on `on` + table; per-row predicates live in the handler.** A predicate like "fire only when the user's plan changed" is a one-line guard at the top of the handler — kept there rather than in a framework pre-filter so the matching rule sits next to the code that reacts to it.
@@ -1688,7 +1880,7 @@ The subscriber sees the post-commit row, which has been auto-stamped by audit/te
 ## See also
 
 - [Subscriptions](/docs/data/subscriptions) — the CLIENT-side `useSubscription` hook for live query data (different concept, similar name).
-- [Streams](/docs/data/streams) — transient element feeds; for crash-safe post-commit work, invoke a workflow from a subscriber.
+- [Streams](/docs/data/streams) — transient element feeds; for crash-safe post-commit work, use a [reaction](/docs/data/reactions) that acts on a workflow.
 
 
 
@@ -1897,6 +2089,99 @@ treating it as permanently consumed would silently swallow a legitimate request.
 `enqueue` returns the outbox row id, which is also the delivery id: persist it
 alongside your row and a client can watch the effect's progress.
 
+## Delivery history
+
+The queue answers "is this still owed". It cannot answer "what did the remote
+say on attempt 3", "how long did it take", or "who resent it" — which is what a
+delivery-history screen renders. So every attempt appends a row to
+`_voltro_outbox_attempts`:
+
+| column | |
+|---|---|
+| `outboxId` | the entry this attempt belongs to |
+| `effect` | denormalised — the history stays readable after the entry is purged |
+| `attempt` | 1-indexed, monotonic across the entry's whole life |
+| `trigger` | `automatic` (the drain) or `manual` (a resend) |
+| `triggeredBy` / `reason` | who asked for a manual resend, and why |
+| `outcome` | `delivered` · `failed` · `dead` (`dead` = the attempt that exhausted the budget) |
+| `startedAt` / `finishedAt` / `durationMs` | timing |
+| `error` | failure message (clipped) |
+| `response` | whatever the handler **returned**, as JSON |
+| `subjectId` / `tenantId` / `traceId` | carried from the entry |
+
+`response` is how per-attempt transport detail gets recorded without the
+framework pretending to model HTTP — return `{ status, body }` from the handler
+and the history has it:
+
+```ts
+export default defineOutboxHandler({
+  effect: 'jira.sync',
+  handler: async ({ payload }) => {
+    const res = await fetch(url, { method: 'POST', body: JSON.stringify(payload) })
+    if (!res.ok) throw new Error(`jira ${res.status}`)
+    return { status: res.status, body: (await res.text()).slice(0, 500) }
+  },
+})
+```
+
+It is a framework table like any other, so reading it is a normal store read —
+there is no separate history API to learn:
+
+```ts
+const history = await ctx.store.query({
+  table: '_voltro_outbox_attempts',
+  predicate: eq('outboxId', deliveryId),
+  order: [{ column: 'attempt', direction: 'desc' }],
+  take: 20,
+})
+```
+
+Attempts are recorded best-effort: if the log write fails, the delivery still
+succeeds. History must never be able to break the thing it observes.
+
+## Resending on demand
+
+```ts
+await ctx.outbox.resend(deliveryId, { reason: 'customer never received it' })
+```
+
+Re-arms one entry for delivery now — including one that already reached `dead`.
+This is legitimate precisely because delivery is already at-least-once and
+handlers are therefore already required to be idempotent: a resend is the same
+hazard the contract obliges them to absorb, not a new one.
+
+What it must never be is invisible. The resulting attempt is recorded with
+`trigger: 'manual'` plus the requesting subject and reason, so an operator
+redelivery can never be mistaken for a backoff retry when someone later asks why
+the remote saw the effect twice. The entry also carries a `resendCount`.
+
+Three behaviours worth knowing:
+
+- It **re-arms the existing entry** rather than enqueuing a copy. A copy would
+  carry the same `idempotencyKey`, duplicate the payload, and split one entry's
+  history across two ids.
+- It grants a **small fresh budget** (`attempts`, default 1). A dead entry has
+  already spent its allowance, so without this it would re-die untried — and
+  "try again now" is what the button means, not "restart the whole schedule".
+- It **refuses an entry whose attempt is in flight**, where re-arming would race
+  the running attempt into a double delivery.
+
+## Retention
+
+Two bounds, because an unbounded attempt log is a slow-motion outage:
+
+- A **per-entry cap** (50 attempts) trims the oldest as new ones arrive. The
+  automatic path can't reach it — `maxAttempts` defaults to 8 — so this bounds
+  the one case that is genuinely unbounded: an entry resent by hand for years.
+  It works on every dialect.
+- A **time bound** on the boot sweep purges attempts older than 30 days
+  (`VOLTRO_OUTBOX_ATTEMPTS_TTL_HOURS`), plus **delivered** queue rows
+  (`VOLTRO_OUTBOX_TTL_HOURS`). `dead` and `pending` entries are never aged out —
+  a dead letter is an unresolved incident and a pending one is still owed.
+
+The time sweep runs on postgres; on other dialects the per-entry cap is the
+bound.
+
 ## When NOT to use it
 
 - **Work that must be observable step-by-step, or that suspends** → a
@@ -2504,3 +2789,250 @@ import { ContentForm } from '@voltro/cms/web'
 <ContentForm contentType={blogPost} value={row} onChange={setRow}
   widgets={{ richText: MyTipTapWidget }} />
 ```
+
+
+
+---
+
+<!-- source: en/data/connections.md -->
+## Connections (credentials vault)
+
+_defineConnection — a per-user, encrypted store for third-party credentials, with the OAuth handshake, refresh-before-use, a resolver for handlers and plugins, and a connect UI, from one declaration._
+
+An app that acts on a third party **on behalf of a user** — Jira with that
+user's token, Slack with that user's OAuth grant — needs five things, none of
+them app-specific and all of them easy to get subtly wrong:
+
+1. a per-user token table,
+2. encryption, so the tokens are not sitting in the database in the clear,
+3. an OAuth authorize/callback pair with anti-CSRF state,
+4. an expiry check with a refresh, without stampeding on the refresh token,
+5. a resolver the request path can ask for "the credential for **this** user".
+
+`defineConnection` is that whole stack from one declaration.
+
+## Declare a connection
+
+One `*.connection.ts` file per connection, default-exported. The file is
+**server-only** — it holds a client secret, and it is never part of the browser
+bundle.
+
+```ts
+// api/connections/jira.connection.ts
+import { defineConnection } from '@voltro/runtime'
+import { serverEnv } from '../env/server'
+
+export default defineConnection({
+  id: 'jira',
+  kind: 'oauth2',
+  label: 'Jira',
+  authorizeUrl: 'https://auth.atlassian.com/authorize',
+  tokenUrl: 'https://auth.atlassian.com/oauth/token',
+  clientId: serverEnv.JIRA_CLIENT_ID,
+  clientSecret: serverEnv.JIRA_CLIENT_SECRET,
+  scopes: ['read:jira-work', 'offline_access'],
+  authorizeParams: { audience: 'api.atlassian.com', prompt: 'consent' },
+  identify: async (tokens) => {
+    const res = await fetch('https://api.atlassian.com/me', {
+      headers: { authorization: `Bearer ${tokens.accessToken}` },
+    })
+    const me = await res.json() as { account_id: string, email: string }
+    return { accountId: me.account_id, accountLabel: me.email }
+  },
+})
+```
+
+For a provider with no OAuth app — or where a personal access token is simply
+the supported path — use `kind: 'pat'`:
+
+```ts
+// api/connections/github.connection.ts
+import { defineConnection } from '@voltro/runtime'
+
+export default defineConnection({
+  id: 'github',
+  kind: 'pat',
+  label: 'GitHub',
+  instructionsUrl: 'https://github.com/settings/tokens',
+  validate: async (token) => {
+    const res = await fetch('https://api.github.com/user', {
+      headers: { authorization: `Bearer ${token}` },
+    })
+    if (!res.ok) throw new Error('GitHub rejected that token')
+    const me = await res.json() as { login: string }
+    return { accountLabel: me.login }
+  },
+})
+```
+
+`validate` is worth writing. Without it, a mistyped token is accepted happily
+and fails hours later inside a background job; with it, the user finds out while
+they still have the token on their clipboard.
+
+## Use the credential
+
+`ctx.connections.get(id)` returns the **calling subject's** credential,
+refreshed if it was near expiry. There is no parameter for "some other
+subject" — the facade is bound to the request.
+
+```ts
+// api/actions/syncIssues.action.server.ts
+export default async function syncIssues(input: { projectKey: string }, ctx) {
+  const jira = await ctx.connections.get('jira')
+
+  const res = await fetch(`https://api.atlassian.com/ex/jira/search?jql=project=${input.projectKey}`, {
+    headers: { authorization: `Bearer ${jira.accessToken}` },
+  })
+  return { count: (await res.json()).total }
+}
+```
+
+Use `ctx.connections.tryGet(id)` for the "use it if we have it" branch — it
+returns `null` when nothing is connected. A failing *refresh* still throws:
+silently degrading a connected-but-broken account to "not connected" would hide
+a revoked grant behind a feature that quietly does nothing.
+
+`ctx.connections` is **absent** when the app declares no `*.connection.ts`, so
+reaching for it in an app with no connections is a type error rather than a
+runtime surprise.
+
+## The connect UI
+
+`useConnection` gives you one connection's live state plus its operations.
+Everything reactive comes from a single subscription, so a completed OAuth
+callback updates an open settings page with no polling.
+
+```tsx
+import { useConnection } from '@voltro/client'
+import { ConnectAccount } from '@voltro/ui'
+
+export const IntegrationSettings = () => {
+  const jira = useConnection('app', 'jira')
+  const github = useConnection('app', 'github')
+
+  return (
+    <>
+      <ConnectAccount connection={jira} loading={jira.loading} />
+      <ConnectAccount connection={github} instructionsUrl="https://github.com/settings/tokens" />
+    </>
+  )
+}
+```
+
+`useConnections('app')` returns the whole list if you would rather render the
+page yourself:
+
+```tsx
+const { connections, get, loading } = useConnections('app')
+// each entry: { connectionId, kind, label, status, accountLabel, scopes, expiresAt, lastError }
+```
+
+`connect()` opens the provider's consent screen in a popup by default (which
+keeps the current page — and any unsaved form state — mounted) and falls back to
+a full navigation when the popup is blocked. Pass `{ mode: 'redirect' }` to
+navigate the tab instead.
+
+**The token is never on the client.** The wire shape carries status, account and
+expiry — nothing else. If you find yourself wanting the token in the browser,
+the call that needs it belongs on the server.
+
+## Status
+
+| Status | Meaning |
+| --- | --- |
+| `disconnected` | No credential on file for this user. |
+| `connected` | A usable credential is on file. |
+| `expired` | The access token is past its deadline and there is no refresh token. Re-consent needed. |
+| `revoked` | The provider **refused** the refresh. The stored tokens were cleared; only reconnecting restores it. |
+| `error` | The last refresh failed transiently (5xx / network). Tokens retained; the next use retries. |
+
+`expired`/`revoked`/`error` are deliberately not "connected" — that distinction
+is what makes the UI prompt rather than silently do nothing.
+
+## Encryption is not optional
+
+Tokens are written through the framework's field cipher — the same
+`FieldCipher` `.encrypted()` columns use, not a second mechanism with its own
+key management. **An app that declares a connection and has no cipher
+configured refuses to boot**, with a message naming the connections. There is no
+plaintext fallback and no warn-and-continue path.
+
+```ts
+// app.config.ts
+import { governancePlugin } from '@voltro/plugin-governance'
+
+export default defineApiConfig({
+  plugins: [
+    governancePlugin({ fieldEncryption: { secretKey: 'VOLTRO_FIELD_ENCRYPTION_KEY' } }),
+  ],
+})
+```
+
+## Refresh
+
+Resolving checks the deadline with 60s of skew and renews **ahead** of it, so no
+call site needs a retry-on-401 dance. Two layers keep concurrent refreshes from
+stampeding:
+
+- an in-process single-flight, so many handlers on one replica share one
+  refresh;
+- a compare-and-set lease on the row, so two **replicas** do not both spend the
+  refresh token — which, with a provider that rotates refresh tokens, would
+  invalidate the grant outright.
+
+A provider that does not rotate simply omits `refresh_token` from its reply; the
+existing one is kept rather than overwritten with null.
+
+## Plugins
+
+A plugin never sees a request context, so the vault also publishes a
+process-level resolver. `@voltro/plugin-atlassian` consumes it directly:
+
+```ts
+// app.config.ts
+import { atlassianPlugin } from '@voltro/plugin-atlassian'
+import { connectionCredentials } from '@voltro/plugin-atlassian/connection'
+
+plugins: [
+  atlassianPlugin({
+    credentialsResolver: connectionCredentials({
+      connectionId: 'jira',
+      baseUrl: serverEnv.JIRA_BASE_URL,
+    }),
+  }),
+]
+```
+
+The plugin's contract is unchanged — it still receives a
+`(subject) => Effect<AtlassianCredentials>` and still never reads your schema.
+What changes is who owns the token. A plugin with its own credential resolver
+keeps working exactly as before; this is an additional way to satisfy the same
+option, not a replacement.
+
+## What the framework stores
+
+Two tables, created only when the app declares a connection:
+
+- `_voltro_connections` — one row per (connection, subject). Access and refresh
+  tokens are ciphertext. Reactive, which is what makes the connect UI live.
+- `_voltro_connection_grants` — an in-flight OAuth handshake (single-use state,
+  encrypted PKCE verifier, 10-minute TTL).
+
+The callback endpoint is `GET /_voltro/connections/<id>/callback`, mounted
+automatically under both `voltro dev` and `voltro serve`. Register it as the
+redirect URI on your OAuth app, or set `redirectUri` on the declaration. The
+app's public origin comes from `VOLTRO_PUBLIC_URL`.
+
+## Deliberate non-goals
+
+- **Disconnect does not revoke at the provider.** Providers disagree on whether
+  a revocation endpoint exists, what it takes, and whether it kills sibling
+  sessions. `disconnect()` forgets our copy and says so, rather than pretending
+  to a revocation it cannot guarantee. Revoke in the provider's own UI when that
+  matters.
+- **No app-wide connection.** A credential belongs to a subject. An anonymous
+  caller is refused rather than bucketed under a shared pseudo-subject, which
+  would be a credential every visitor shares. For a service account, store it as
+  a secret, not a connection.
+- **`redirectTo` is a same-origin path only.** An absolute URL is rejected —
+  otherwise every app declaring a connection would ship an open redirector.