@voltro/cli 0.25.0 → 0.27.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
+import { Z as e } from "./inspectMetrics-BU90mvJN.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-5ZFiNO1R.js";
+import { t as r } from "./serveCommand-DfkisVWP.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-C-ZWSDpg.js → start-BGXIf6zT.js}

@@ -1,5 +1,5 @@
-import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-EQwH7BI4.js";
-import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-DuLUrZp9.js";
+import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-BU90mvJN.js";
+import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-CUCCzw2I.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as F, extname as I, join as L, resolve as R } from "node:path";
 import { fileURLToPath as z, pathToFileURL as B } from "node:url";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
-import { t } from "./start-C-ZWSDpg.js";
+import { Z as e } from "./inspectMetrics-BU90mvJN.js";
+import { t } from "./start-BGXIf6zT.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.25.0",
-    "@voltro/cache": "0.25.0",
-    "@voltro/data-transfer": "0.25.0",
-    "@voltro/database": "0.25.0",
-    "@voltro/env": "0.25.0",
-    "@voltro/kv": "0.25.0",
-    "@voltro/logger": "0.25.0",
-    "@voltro/plugin-auth": "0.25.0",
-    "@voltro/plugin-broadcast": "0.25.0",
-    "@voltro/plugin-mail": "0.25.0",
-    "@voltro/plugin-storage": "0.25.0",
-    "@voltro/plugin-webhooks": "0.25.0",
-    "@voltro/protocol": "0.25.0",
-    "@voltro/runtime": "0.25.0",
-    "@voltro/serverless": "0.25.0",
-    "@voltro/workflow": "0.25.0",
+    "@voltro/ai": "0.27.0",
+    "@voltro/cache": "0.27.0",
+    "@voltro/data-transfer": "0.27.0",
+    "@voltro/database": "0.27.0",
+    "@voltro/env": "0.27.0",
+    "@voltro/kv": "0.27.0",
+    "@voltro/logger": "0.27.0",
+    "@voltro/plugin-auth": "0.27.0",
+    "@voltro/plugin-broadcast": "0.27.0",
+    "@voltro/plugin-mail": "0.27.0",
+    "@voltro/plugin-storage": "0.27.0",
+    "@voltro/plugin-webhooks": "0.27.0",
+    "@voltro/protocol": "0.27.0",
+    "@voltro/runtime": "0.27.0",
+    "@voltro/serverless": "0.27.0",
+    "@voltro/workflow": "0.27.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -602,7 +602,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.25.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.26.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.25.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.26.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/data.md

@@ -536,6 +536,32 @@ Queries are streaming RPCs whose elements are **subscription events**: an initia
 - **Using a stream for durable data.** Streams are transient. Persist rows and expose them through a query when the UI should survive reloads or sync across tabs.
 
 
+## Contradictions refused at declaration
+
+```ts
+defineQuery({ name: 'q', guards: [], … })              // ✗ enforces nothing
+defineQuery({ name: 'q', source: '', … })              // ✗ reactive, subscribed to nothing
+defineQuery({ name: 'q', internal: true, overridesPlugin: true, … })  // ✗ removes, replaces nothing
+```
+
+The same three shapes `defineEvent` refuses, for the same reasons — a rule that
+holds for one primitive and not another is worse than no rule, because the
+answer then depends on which file you happened to open.
+
+**`guards: []`** reads at the call site as if the procedure were protected and
+enforces nothing; the check runs only for a non-empty list. Omit the field.
+
+**An empty `source`** declares reactivity and subscribes to nothing: the query
+serves one snapshot and never updates, which is indistinguishable from "nothing
+changed". Worse than a *stale* source, which the boot warning can at least name
+— this one names no table at all, so nothing can report it.
+
+**`internal: true` + `overridesPlugin`** removes the plugin's route and puts
+something unreachable in its place: callers get a 404 for something that used to
+work, with no diff that says so. Joins the existing refusals of `internal` with
+`publicApi` or `exposeAsTool`.
+
+
 ## Loading vs empty — don't conflate them
 
 `useSubscription` returns `loading` and `isEmpty` alongside `data`. They are
@@ -1469,6 +1495,38 @@ Tables with the `tenant()` mixin are scoped by the runtime using `ctx.request.su
 
 The devtools subscription surfaces show active subscribers, recent deltas, and cache state. Use them when a query updates too often or not at all.
 
+## Cost — how large may a live query be?
+
+Every change re-runs the query and diffs the WHOLE result against the previous
+one, so the cost is linear in the RESULT SIZE, not in the size of the change.
+Measured on `diffRows`:
+
+| result rows | one column changed | every row replaced |
+| --- | --- | --- |
+| 50 | 45 µs | — |
+| 500 | 480 µs | — |
+| 2 000 | 1.23 ms | 1.29 ms |
+| 5 000 | 3.1 ms | — |
+
+Two things follow, and the second is the one that surprises people:
+
+- **The curve is linear, not quadratic.** Per-row cost is flat across a 100×
+  growth (910 ns → 625 ns), so a large result gets slower in proportion and
+  never falls off a cliff.
+- **A one-column edit costs the same as replacing everything.** 2 000 rows with
+  a single change is 1.23 ms; the same 2 000 rows entirely replaced is 1.29 ms —
+  5 % more. The cost is the WALK, not the delta. Making your mutation smaller
+  does not make the subscription cheaper.
+
+So the number to design against is the RESULT SIZE. A few hundred rows is free.
+A 5 000-row live query costs 3.1 ms of CPU per change, per replica — fine for a
+dashboard that changes a few times a minute, wrong for one fed by a high-rate
+writer. Page the query, or narrow it with a predicate, rather than reaching for
+a bigger machine.
+
+These numbers are asserted by `rowPatch.perf.test.ts`, so they are current
+rather than a note somebody wrote down once.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -1663,6 +1721,13 @@ export default (input, ctx) => Effect.gen(function* () {
 
 Three typed errors reach the **producer**, so a mismatch is one failing call rather than every consumer's handler breaking on a field that is not there: `EventPayloadInvalid`, `EventKeyInvalid`, `EventPayloadTooLarge`.
 
+`EventPayloadTooLarge` fires at **7,500 bytes** for the encoded envelope (event
+name + key + payload, as JSON). The ceiling is not arbitrary and it is not a
+transport limit to tune around: an event says that something *happened*, so
+`photo.added` carries a photo REFERENCE and the consumer fetches the photo
+through a route that can stream, cache and authorize it. A payload approaching
+this size is usually a read that has been pushed into a notification.
+
 <Callout>
 **Both handler styles publish.** `ctx.events.publish` returns an Effect, so the
 `Effect.gen` form above is the idiomatic one — but `await ctx.events.publish(…)`
@@ -1689,11 +1754,36 @@ Everything you would otherwise hand-roll is gone, and each of these was a real b
 - **A key change is a clean switch** — the old subscription ends before the new one starts.
 - **`key: null` means "not yet"**: no subscription, `status: 'idle'`. You never need a placeholder key.
 
+## Showing that it is showing stale
+
+`useEvent` returns `{ status, missed, lastMiss }` — `status` is
+`'idle' | 'connecting' | 'live'`, so `status === 'live'` is your connected flag
+and needs no extra plumbing.
+
+```tsx
+const { status, missed } = useEvent(gameStarted, { arenaId }, onStart)
+
+// A screen nobody is standing at should say when it stopped being current.
+{status !== 'live' && <Badge>reconnecting…</Badge>}
+{missed > 0 && <Badge>{missed} missed — refreshing</Badge>}
+```
+
+This matters most where nobody is watching the tab. A wall display that loses
+its connection keeps rendering the last thing it received, and from across the
+room "stale" and "current" look identical. The difference between *showing old
+data* and *showing that it is showing old data* is one badge.
+
+`missed` is the other half: it is COMPUTED, never estimated, so a non-zero value
+means deliveries provably did not arrive — worth surfacing rather than hiding,
+because the refresh that follows is visible anyway.
+
+
 ## What it guarantees — read this before you build on it
 
 - **At-most-once, best-effort, live.** No persistence, no retry, no redelivery. For guarantees use the [outbox](/docs/data/outbox); this is the other axis.
 - **Ordered per publishing instance per key.** *Not* globally per key — two instances publishing the same key have no shared counter, and we do not promise an order we cannot keep.
-- **Guards are re-checked when the subject changes**, not per delivery. Revoke a role and the stream ends.
+- **Guards are re-checked on EVERY delivery**, exactly as a live query's are. A resource-scoped guard (`{ scope: 'arena:read', from: 'arenaId' }`) runs its resolver each time, so un-sharing a resource or ending a membership stops the stream at the next delivery — the client is told, not silently skipped. What this does *not* catch is a ROLE revoked on the subject itself: those scopes were captured when the subscription opened. That half is covered by the credential bound below.
+- **A subscription cannot outlive the credential that authorized it.** When the session carries an expiry, the stream ends at it — and `useEvent` reconnects immediately, which is a NEW request, so the subject is resolved afresh and the guards run again for real. Still entitled: it continues and your app sees nothing. No longer entitled: the reconnect is refused, loudly. You write no reconnect handling for this; it is the existing retry doing its job. Note the limit precisely — this bounds EXPIRY, not revocation.
 - **Payloads are capped at 7,500 bytes** of encoded envelope, on **every** dialect. An event says something happened, so carry a photo *reference*, not a photo.
 
 ### `missed` is a number, not a feeling
@@ -1742,7 +1832,7 @@ export const orderPaid = defineEvent({
 
 One `publish` now reaches connected clients, every matching workflow trigger, and every subscribed HTTP target. Without this an app that does both declares the thing twice, in two shapes, and the two drift.
 
-The `webhook:` block is namespaced because its settings mean nothing to the other audiences — a top-level `retry` would read as if it applied to client delivery, which is at-most-once by design and has no retry at all. Requires [`@voltro/plugin-webhooks`](/docs/plugins/webhooks); absent, it costs nothing.
+The `webhook:` block is namespaced because its settings mean nothing to the other audiences — a top-level `rateLimit` would read as if it throttled client delivery, which it does not — it is a ceiling on webhook deliveries only. Requires [`@voltro/plugin-webhooks`](/docs/plugins/webhooks); absent, it costs nothing.
 
 ## Across instances
 
@@ -1763,6 +1853,144 @@ consequence: during a **rolling deploy** replicas on different framework version
 use different channel names, so cross-replica delivery is degraded for the length
 of the rollout. Local delivery on each replica is unaffected throughout.
 
+## Measured against socket.io
+
+Same machine, same Redis, same topology, back to back:
+
+| | p50 (median of 5) | p50 range | p99 (median of 5) | p99 range |
+| --- | --- | --- | --- | --- |
+| **Voltro**, publisher → Redis → subscriber | **0.68 ms** | 0.58–0.86 | 7.01 ms | 4.50–13.36 |
+| **socket.io + @socket.io/redis-adapter** | 1.31 ms | 1.16–1.73 | **4.52 ms** | 4.33–7.83 |
+
+Five runs each, alternating, on one machine. **The p50 ranges do not overlap —
+that is a real ~2x advantage.** The p99 ranges DO overlap, so the tail difference
+is weaker evidence than the medians.
+
+**An earlier version of this table reported one run each** and claimed "32%
+faster at the median, 44% worse at the tail". Both numbers were noise: the
+median advantage is nearer 2x and the tail gap is inside the overlap. A single
+measurement presented as a fact is the defect this framework spends its time
+removing, and it was committed here.
+
+**Where our tail comes from, measured rather than guessed.** Splitting the
+publish path: our own code — building the envelope, the Effect fiber, handing
+off — costs **p50 0.056 ms / p99 0.444 ms**. Waiting for Redis to acknowledge
+costs **p50 1.17 ms / p99 6.43 ms**. So roughly 0.4 ms of a 7 ms tail is ours;
+the rest is the broker round-trip, which socket.io pays too. There is no
+code-level tail defect to fix here — on this machine the number is dominated by
+Docker's network stack.
+
+The script is in the repo (`scripts/bench/socketio-cross-replica.mjs`) so the
+number can be re-taken rather than believed. It is not a test: keeping a
+competitor in the dependency tree to hold a number green is the wrong trade.
+
+**Topology is what makes this a comparison at all.** Two server instances share
+one Redis; the client hangs off instance B and every emit is issued on instance
+A. The first version measured socket.io on a plain localhost websocket and came
+out 3x faster — which proved nothing, because that is one hop and this is two
+through a broker.
+
+Hosted products (Firebase, Pusher, Ably) are deliberately absent. Measuring them
+honestly needs their accounts, regions and tiers, and a wrong number about
+someone else's product is worse than no number.
+
+
+## The hard questions, and our answers
+
+| the question | the answer here |
+| --- | --- |
+| Does a client learn that deliveries were missed? | Yes — `missed` is COMPUTED from per-origin serials against a watermark, never estimated |
+| Can a late arrival tell "nothing happened" from "I was not listening"? | Yes — every delivery carries `prior`, the watermark before it was accepted |
+| Is a subscription authorized, or only the connection? | Per subscription, on the routing key, re-checked per delivery |
+| Does a subscription outlive the credential that authorized it? | No — bounded by the credential's verified expiry, cookie AND bearer |
+| Does the link heal itself after a broker outage? | Yes — no restart, no app-side retry, no resubscribe |
+| Does a degraded network lose messages or only slow them? | Only slows them — 7x the median latency, zero loss |
+| Does fan-out cost grow with subscriber count? | No — 0.027 µs per delivery, flat from 1 to 100 |
+| Are channels typed, or strings? | Typed — a rename is a compile error |
+| Is a declared event nothing publishes reported? | Yes, at boot, reading sibling apps in the workspace |
+| Is cross-replica fan-out separated per app by default? | Yes — the namespace derives from the app name |
+
+**Every row is enforced by a test** (`realtimeProperties.test.ts`) that fails if
+the proof behind it disappears. A property may not be claimed here without
+something in the repository that demonstrates it.
+
+**Why this is not a benchmark against other products.** A table of our measured
+numbers beside someone else's published ones is not a comparison — it is two
+things in a row. Benchmarking a hosted competitor honestly needs their accounts,
+regions, tiers and retry policies, and a wrong number about someone else's
+product is worse than no number. What decides a choice anyway is not the
+microseconds; it is whether the system answers these questions at all. Each
+answer above is checkable against this repository by anyone, which is the
+opposite of a claim.
+
+
+## What you can build — and what to reach for
+
+| what you want to build | reach for |
+| --- | --- |
+| a list that updates as rows change | `useSubscription` |
+| a huge list without loading all of it | `useWindowedSubscription` |
+| an edit that appears before the server confirms | `useMutation` (optimistic is derived) |
+| a signal with no row behind it — a game start, a trigger | `defineEvent` |
+| a 60 Hz value where only the newest matters | `defineEvent` + `delivery: 'latest'` |
+| knowing a delivery was provably missed | `useEvent` → `missed` |
+| who is online in a room | `usePresence` |
+| who is typing right now | `useTyping` |
+| showing that the screen went stale | `useEvent` → `status`, or `useConnectionStatus` |
+| fan-out across replicas | `broadcastPlugin()` |
+| durable work with progress a client can watch | `useWorkflow` |
+| an in-app inbox | `useInbox` |
+| delivering an event to a third party | `@voltro/plugin-webhooks` |
+| gating who may subscribe | `guards:` on the event |
+| an upload whose progress the UI follows | `useUpload` |
+
+This table is a TEST (`realtimeCapabilities.test.ts`), not a claim: each row
+asserts its primitive is still exported, so a capability that loses its
+primitive to a rename goes red in CI rather than being discovered by whoever
+tries to build it.
+
+**Three of these are the ones people usually reach for wrongly.** A value that
+changes many times a second is an EVENT, not a row — writing it to a table wakes
+every subscriber of every query reading that table, and each pays a full re-diff.
+"Who is online" is presence rather than a table, because the answer is ephemeral
+and per-connection. And "did anything get lost" has a real answer (`missed`),
+computed rather than estimated, so you do not have to build a heartbeat of your
+own to find out.
+
+
+## The four costs side by side
+
+Every number below is asserted by a test in the repo, not quoted from a report —
+each surface has a `*.perf.test.ts` that prints what it measured.
+
+| primitive | operation | cost | scales with |
+| --- | --- | --- | --- |
+| **Events** | `ctx.events.publish` | **4.3 µs** (~232 k/s) | nothing — flat |
+| **Events** | delivery to a subscriber | **0.027 µs** | subscribers, linearly and cheaply |
+| **Presence** | a heartbeat | **0.16 µs** | nothing — flat |
+| **Presence** | a roster read, 10 k members | **547 µs** | the ROOM |
+| **Records** | a live query re-diff, 5 000 rows | **3 062 µs** | the RESULT SET |
+| **Broadcast** | cross-replica, real Redis | **p50 1.1 ms · p99 11.2 ms** | the network |
+
+**The comparison is the useful part.** Publishing an event costs about a
+thousandth of what re-diffing a large live query does, and that ratio — not
+either number — is what should decide between them. A value that changes at 60 Hz
+belongs in an event; the same value written to a table wakes every subscriber of
+every query reading it, and each pays the full walk.
+
+**Two of the four are flat and two are not.** A publish and a heartbeat cost the
+same whatever the load, so they scale by adding replicas. A roster read is
+linear in the room and a live-query diff is linear in the RESULT SET — including
+when one column of one row changed, because the cost is the walk rather than the
+patch. Those are the two numbers to keep an eye on as an app grows.
+
+**Cross-replica adds milliseconds, not microseconds**, and that is a network
+crossing rather than framework overhead. Under an injected 20 ms ± 10 jitter it
+becomes p50 26 ms / p99 89 ms; adding a 50 KB/s ceiling makes it p50 188 ms — and
+in every one of those runs, all 200 messages arrive. Degradation costs latency,
+never messages.
+
+
 ## Throughput — the numbers, and where this is the wrong primitive
 
 Measured on one core, publish path only:
@@ -1891,6 +2119,30 @@ Three bugs in nine lines, and every consumer has to get all three right: the `se
 
 Migrating is mechanical: declare the event, replace the insert with `ctx.events.publish`, replace the hook with `useEvent`, and drop the table.
 
+## What `defineEvent` refuses, and why
+
+```ts
+defineEvent({ name: 'orders paid', … })              // ✗ whitespace — see below
+defineEvent({ name: 'orders.paid', guards: [], … })  // ✗ enforces nothing
+defineEvent({ name: 'x', webhook: { rateLimit: { perMinute: 0 } } })  // ✗ never delivers
+```
+
+**Whitespace in a name is a broker-level failure, not a style rule.** The name
+becomes a broker SUBJECT segment. NATS refuses a subject containing whitespace
+and delivers nothing — with no error on the publishing side. An app that works
+on Redis therefore stops working when the transport changes, silently and in
+production only. Use a dot to namespace: `orders.paid`.
+
+**`guards: []` is refused** because it reads at the call site as if the event
+were protected and enforces nothing — the empty list never reaches the check.
+Omit the field for an unguarded event.
+
+**`rateLimit: { perMinute: 0 }`** defers every delivery forever. There is no
+"unlimited" spelling — omit `rateLimit` for no ceiling. **`version: 0`** would
+make a subscriber pinned to 1 read the event as *behind*, the opposite of what a
+bump is for.
+
+
 ## See also
 
 [Subscriptions](/docs/data/subscriptions) · [Outbox](/docs/data/outbox) · [Subscribers](/docs/data/subscribers) · [Streams](/docs/data/streams)

package/templates/agent-docs/database/schema.md

@@ -423,6 +423,53 @@ the framework ships richer types for specific use cases:
 - **[JSON](/docs/database/json)** — `json<T>()` for arbitrary nested
   data; native JSONB on postgres.
 
+## Pointing at a plugin-owned row — `pluginRef`
+
+```ts
+import { pluginRef } from '@voltro/database'
+import { aiFlowsTable } from '@voltro/plugin-ai-flows'
+
+export const favourites = table('favourites', {
+  id: id(),
+  flowId:     pluginRef(aiFlowsTable, { orphanPolicy: 'delete' }),
+  sharedFlow: pluginRef(aiFlowsTable, { orphanPolicy: 'null' }).nullable(),
+})
+```
+
+A plain typed id column with **no foreign key**, plus a declared orphan rule the
+framework runs on the post-commit change channel.
+
+**Reach for `reference()` first.** A real foreign key across a plugin boundary
+works and survives the plugin renaming its table, because `reference()` takes
+the table as a VALUE — see
+[plugins/overview](/docs/plugins/overview#pointing-your-table-at-a-plugins-row).
+`pluginRef` is for the case where you have deliberately chosen NOT to have a
+key: it enforces nothing at the database level.
+
+What it restores is the piece that goes missing with that choice — not the
+constraint but the RULE, which otherwise becomes a hand-written subscriber per
+app that nobody notices the absence of.
+
+| policy | on the target's delete |
+| --- | --- |
+| `'delete'` | delete the referencing row — for one that only exists to point (a favourite, a pin, a share) |
+| `'null'` | clear the column, keep the row. Requires `.nullable()` |
+| `'keep'` (default) | nothing — the explicit "I handle it myself" |
+
+Four things worth knowing before you rely on it:
+
+- **The tenant boundary fails closed.** A referencing row whose tenant differs
+  from the deleted row's — or which has none — is left alone. Deleting across a
+  tenant boundary because a scope was missing is worse than leaving an orphan.
+- **Soft deletes are opt-in** (`onSoftDelete: true`). A soft delete is a state
+  the target can undo, so cascading on it destroys rows a restore cannot bring
+  back — and plugin tables are inconsistent about carrying `deletedAt` at all.
+- **The target is a table VALUE.** A rename carries the rule with it, which is
+  the whole reason the FK was refused; a string would put the coupling back.
+- **A missing plugin refuses at boot**, naming both sides. A declared rule
+  against a table nothing registers would sit there looking enforced.
+
+
 ## Anti-patterns
 
 - **`serial`/`bigserial` integer ids.** Leaks row counts via `/users/12345`. Use `id()` (TypeID).

package/templates/agent-docs/deployment.md

@@ -1150,6 +1150,24 @@ KV_BACKEND=redis
 
 Schedules and aggregates auto-coordinate via an advisory lock on SQL stores — no extra config to keep them from double-firing across replicas.
 
+### Workflow failover across replicas
+
+On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:
+
+- **Inject `POD_IP`** (K8s downward API, `fieldRef: status.podIP`) or set `VOLTRO_WORKFLOW_RUNNER_HOST`. This is each replica's cluster **identity** — without a distinct value, every replica registers as the *same* runner and they stop distributing shards (and cross-pod resume degrades). The boot logs a warning if it sees `localhost` with SQL storage.
+- **Make step side effects idempotent.** Failover is *at-least-once at the step boundary*: a crash between a side effect and its journal write re-runs that step. A step's own [`retry:`](/docs/workflows/retries) does not change this — it's about the step you're inside, not the replica handoff.
+
+**Is polling the bottleneck? No — reclaim is a lease, not a poll.** A crashed replica keeps its shards until its heartbeat goes stale; only then can a survivor claim them. So takeover latency is bounded by the **lease TTL (~35s by default)**, not by any message-poll interval, and a push mechanism (LISTEN/NOTIFY) does **not** move it. Two knobs tune it:
+
+```sh
+VOLTRO_WORKFLOW_FAILOVER_LEASE=15       # seconds a dead replica's work stays locked (default 35)
+VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT=5    # lease-refresh cadence (default 10; keep ≈ lease/3)
+```
+
+Lower the lease for **faster failover**, at the cost of **false-positive reclaims**: if a *healthy* replica is paused longer than the lease by a GC pause or a DB-latency spike, another replica may briefly also claim its shards. Keep the heartbeat around a third of the lease so one slow refresh doesn't trip a reclaim. For crash detection that doesn't depend on the timeout at all, pair it with a K8s **liveness probe** so a dead pod is removed promptly.
+
+(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. Without a broker, tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` instead. Unrelated to the failover path above.)
+
 ## Checklist
 
 - [ ] `VOLTRO_SESSION_SECRET` set from `voltro secret generate session`, in a secrets manager
@@ -1163,6 +1181,7 @@ Schedules and aggregates auto-coordinate via an advisory lock on SQL stores —
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
 - [ ] `terminationGracePeriodSeconds` generous for graceful drain; `VOLTRO_SHUTDOWN_GRACE_MS` set just under it (minus the preStop sleep)
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
+- [ ] For durable workflows on >1 replica: SQL store + `POD_IP` injected; tune `VOLTRO_WORKFLOW_FAILOVER_LEASE` if a 35s takeover is too slow; step side effects idempotent
 
 
 

package/templates/agent-docs/plugins.md

@@ -166,14 +166,64 @@ the `_voltro_` namespace in 0.22.0, a `reference(() => table)` followed the rena
 **`fk: false`-style decoupling is still available** — declare a plain `text()`
 column instead. Choose it when you deliberately want the app schema independent
 of the plugin's, and accept that nothing then enforces the link. What you should
-NOT do is reach for it by default: an unenforced id column plus a hand-written
-`defineSubscriber` that cleans up on delete is referential integrity re-implemented
-per app, and it is silently wrong the first time somebody forgets it.
+NOT do is reach for it by default.
+
+**When you DO want the decoupling, `pluginRef` gives you the rule without the
+key.** It is a plain typed id column — no constraint, no cross-schema
+dependency — plus a declared orphan policy the framework runs on the post-commit
+change channel:
+
+```ts
+import { pluginRef } from '@voltro/database'
+
+flowId:     pluginRef(aiFlowsTable, { orphanPolicy: 'delete' })
+sharedFlow: pluginRef(aiFlowsTable, { orphanPolicy: 'null' }).nullable()
+```
+
+That closes the gap named above: an unenforced id column plus a hand-written
+`defineSubscriber` that cleans up on delete is referential integrity
+re-implemented per app, and it is silently wrong the first time somebody forgets
+it. The declaration is the same one line either way — the difference is that the
+framework performs it.
+
+**Prefer `reference()` when you want a real key.** `pluginRef` is for the case
+where you have deliberately chosen not to have one; it does not make the
+database enforce anything. The tenant boundary fails closed, soft deletes are
+opt-in (`onSoftDelete`), and a `pluginRef` at a table no installed plugin
+registers refuses at boot rather than sitting there looking enforced.
 
 **`orphanPolicy` is not part of this.** It is migration metadata — how existing
 orphan rows are cleaned up *before* the FK constraint is added — and has no
 runtime semantics. Runtime behaviour comes from `onDelete`.
 
+## Composing with a plugin's namespace
+
+Sharing a namespace with a plugin already works: the collision check compares
+FULL tags, so `notifications.list` of yours beside the plugin's
+`notifications.inbox` is not a clash. Only an identical name is — two handlers
+behind one tag is not something a caller can reason about.
+
+To REPLACE one deliberately, declare it:
+
+```ts
+// Adopt the plugin's namespace, add your own leaves beside it…
+defineQuery({ name: 'notifications.archive', … })
+
+// …and REPLACE just the one you need to behave differently.
+defineMutation({ name: 'notifications.markRead', overridesPlugin: true, … })
+```
+
+The plugin's route is dropped, not merely permitted alongside yours — permitting
+both would leave two handlers bound, which is the state the check exists to
+prevent. The boot logs which routes were replaced.
+
+**Explicit, never inferred.** Letting your route win silently would mean a
+plugin upgrade that adds a route could shadow one of yours with no diff to read.
+It is also why the two obvious alternatives are worse: renaming your procedure,
+or `alias`ing the whole plugin away, both move the split from a domain boundary
+to "who built it" — for whoever calls the api, the worst possible partition.
+
+
 ## When NOT to write a plugin
 
 - **One-off side effect** — just call it from the mutation directly.