@voltro/cli 0.26.0 → 0.27.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 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-XBXuwJty.js";
+import { t as r } from "./serveCommand-DfkisVWP.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.26.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.26.0",
-    "@voltro/cache": "0.26.0",
-    "@voltro/data-transfer": "0.26.0",
-    "@voltro/database": "0.26.0",
-    "@voltro/env": "0.26.0",
-    "@voltro/kv": "0.26.0",
-    "@voltro/logger": "0.26.0",
-    "@voltro/plugin-auth": "0.26.0",
-    "@voltro/plugin-broadcast": "0.26.0",
-    "@voltro/plugin-mail": "0.26.0",
-    "@voltro/plugin-storage": "0.26.0",
-    "@voltro/plugin-webhooks": "0.26.0",
-    "@voltro/protocol": "0.26.0",
-    "@voltro/runtime": "0.26.0",
-    "@voltro/serverless": "0.26.0",
-    "@voltro/workflow": "0.26.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
@@ -1695,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(…)`
@@ -1721,6 +1754,30 @@ 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.
@@ -1796,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:
@@ -1924,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/plugins.md

@@ -196,6 +196,34 @@ registers refuses at boot rather than sitting there looking enforced.
 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.