@voltro/cli 0.23.0 → 0.25.0

package/templates/agent-docs/data.md

@@ -60,6 +60,7 @@ Voltro ships more building blocks than this one section holds — each is a type
 | **Mutation** | `*.mutation.ts` | transactional write → [Mutations](/docs/data/mutations) |
 | **Action** | `*.action.ts` | unary external I/O → [Actions](/docs/data/actions) |
 | **Stream** | `*.stream.ts` | one-shot element push → [Streams](/docs/data/streams) |
+| **Event** | `*.event.ts` | ephemeral fan-out to many clients → [Events](/docs/data/events) |
 | **REST route** | `*.route.tsx` | public raw-HTTP endpoint → [REST routes](/docs/data/rest-routes) |
 | **Aggregate** | `*.aggregate.ts` | scheduled materialised query → [Aggregates](/docs/data/aggregates) |
 | **Subscriber** | `*.subscribe.ts` | per-table post-commit reaction → [Subscribers](/docs/data/subscribers) |
@@ -75,7 +76,7 @@ Voltro ships more building blocks than this one section holds — each is a type
 
 ## What's in this section
 
-**Primitives** — [Queries](/docs/data/queries) (reactive reads + dependency tracking) · [Mutations](/docs/data/mutations) (transactional writes, typed errors, auto-optimistic) · [Actions](/docs/data/actions) (unary RPC, no transaction) · [Subscriptions](/docs/data/subscriptions) (the reactive engine behind snapshots/deltas) · [Streams](/docs/data/streams) (`defineStream` element push) · [REST routes](/docs/data/rest-routes) (public raw-HTTP for third parties) · [Aggregates](/docs/data/aggregates) (scheduled materialised queries) · [Subscribers](/docs/data/subscribers) (per-table post-commit reactions).
+**Primitives** — [Queries](/docs/data/queries) (reactive reads + dependency tracking) · [Mutations](/docs/data/mutations) (transactional writes, typed errors, auto-optimistic) · [Actions](/docs/data/actions) (unary RPC, no transaction) · [Subscriptions](/docs/data/subscriptions) (the reactive engine behind snapshots/deltas) · [Streams](/docs/data/streams) (`defineStream` element push) · [Events](/docs/data/events) (`defineEvent` — things that HAPPEN, with no row behind them) · [REST routes](/docs/data/rest-routes) (public raw-HTTP for third parties) · [Aggregates](/docs/data/aggregates) (scheduled materialised queries) · [Subscribers](/docs/data/subscribers) (per-table post-commit reactions).
 
 **Protocol & errors** — [Wire protocol](/docs/data/wire-protocol) (framing, multiplexing) · [Error handling](/docs/data/errors) (Schema-tagged errors, retries, client narrowing).
 
@@ -130,7 +131,7 @@ Every executor receives `ctx.request.subject` — the typed identity of the call
 | Transient server-to-client element stream | `*.stream.ts` + `*.stream.server.ts` + `useAgentStream` |
 | Durable persisted AI chat | `*.agent.tsx` or action + query over `agent_messages` |
 | Background job | `*.workflow.tsx` |
-| Fan a domain event out to one or more workflows | [`*.trigger.tsx`](/docs/workflows/event-triggers) + `ctx.events.emit(...)` |
+| Fan a domain event out to one or more workflows | [`*.trigger.tsx`](/docs/workflows/event-triggers) + `ctx.events.publish(...)` |
 | Pre-computed query result (top-N, summary) | [`*.aggregate.ts`](/docs/data/aggregates) |
 | React to every commit on a table (server-side) | [`*.subscribe.ts`](/docs/data/subscribers) |
 | Event ingestion + analytical aggregates over events | [Analytics sink](/docs/plugins/analytics) |
@@ -816,6 +817,26 @@ try {
 
 The same applies to `run` on [actions](/docs/data/actions).
 
+## Idempotency — a retried mutation runs exactly once
+
+The reactive client resends an in-flight mutation after a network blip. Without a guard, "create order" or "charge card" would run twice. `useMutation` (and `useAction`) mint a fresh **idempotency key** per call and attach it to the rpc frame; when idempotency is enabled the server dedupes a repeat of that key — the handler runs once and the retry replays the first result.
+
+Enable it once (this also covers the REST `Idempotency-Key` header — one switch, both surfaces):
+
+```ts
+// app.config.ts
+export default {
+  idempotency: true, // or { ttlMs: 600_000 } — the dedup window (default 24h)
+}
+```
+
+For a HIGHER-level guarantee — dedupe a double-click or an offline resend of the *same logical action* — pass a STABLE key derived from the action's identity, instead of the per-call one:
+
+```ts
+await placeOrder.mutate(cart, { idempotencyKey: `order:${cart.id}` })
+```
+
+The key is scoped to `(tenant, subject, mutation)`, so one user's key can never replay another's. The replayed result is byte-for-byte the first one — a `Date` in the output comes back a `Date`, not a string — because it round-trips through the mutation's output schema. Off by default: with no `idempotency` config, every call runs.
 
 ## Auto-Optimistic
 
@@ -1573,6 +1594,309 @@ See [AI streaming](/docs/ai/streaming) and [Agents](/docs/ai/agents) for those p
 
 
 
+---
+
+<!-- source: en/data/events.md -->
+## Events
+
+_`*.event.ts` — ephemeral fan-out to connected clients with defineEvent, ctx.events.publish and useEvent. At-most-once, live, and it tells you when it lost something._
+
+An **event** is a thing that *happened*. It has a time and no value afterwards — where a table row has a value and no time.
+
+That distinction decides which primitive you want, and it is the only decision here that is hard to reverse later:
+
+| You are modelling | Use | Because |
+| --- | --- | --- |
+| **what happened** — a game started, a door opened, a terminal confirmed a payment | **Events** (this page) | nothing to store; a late arrival wants what happens *next*, not the history |
+| **what is** — the current roster, an order's status, a document | [Queries](/docs/data/queries) + [Subscriptions](/docs/data/subscriptions) | a late arrival wants the current value immediately |
+| **what must happen, even if we crash** — charge a card, send an invoice | [Outbox](/docs/data/outbox) | needs persistence, retries and a delivery guarantee |
+
+If you find yourself writing a table so that a subscriber fires, you want an event.
+
+## Declare it
+
+```ts
+// events/gameLifecycle.event.ts
+import { defineEvent } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const gameStarted = defineEvent({
+  name: 'games.started',
+  key: Schema.Struct({ arenaId: Schema.String }),
+  payload: Schema.Struct({
+    gameId: Schema.String,
+    gameType: Schema.Literal('evo5', 'evo6'),
+    startedAt: Schema.Number,
+  }),
+  guards: [{ scope: 'display:read' }],
+})
+```
+
+A `*.event.ts` file is **browser-safe** and may hold several declarations — a lifecycle's stages are one concept. Client and server import the *same* value, which is what makes the key and payload types identical at both ends.
+
+**`key` is the address, and only the address.** A subscriber receives events published under a key it asked for, so the server never sends the others at all. Put in it what *routes* (`arenaId`) and nothing else — a discriminator your handler reads (`gameType`) is payload. Every key field fragments the subscriber set.
+
+**`guards` decide who may listen**, in the same vocabulary a query uses, and they are checked *before* the subscription is registered — a refused client never holds one. The routing key is the guard input, so a resource-scoped guard (`{ scope: 'arena:read', from: 'arenaId' }`) sees which arena was asked for. A refusal reaches the client as the `ScopeError` the rpc declares.
+
+**The tenant is not part of the key and must never be added.** It comes from the subject on both sides, so a cross-tenant delivery is impossible by construction rather than by remembering to filter.
+
+The name shares the rpc tag space. Two declarations answering to one name fail the **boot**, not the first delivery.
+
+## Publish it
+
+Only the server publishes. A client-originated event is an [action](/docs/data/actions) that publishes — which means every publish has already passed a guard-checked, typed handler, and there is no "who may write to this channel" question to answer.
+
+```ts
+// actions/reportGameEvent.action.server.ts
+export default (input, ctx) => Effect.gen(function* () {
+  yield* ctx.events.publish(gameStarted, { arenaId: input.arenaId }, {
+    gameId: input.gameId,
+    gameType: 'evo5',
+    startedAt: Date.now(),
+  })
+})
+```
+
+`publish` works from anywhere with a `ctx`: an action, a mutation, a workflow, a subscriber, a cron, a startup hook.
+
+**Inside a mutation it fires on COMMIT, and not at all on rollback.** That is not a nicety: a display reacting to a game start the database rolled back happens on every constraint violation, every deadlock retry, every guard that fails *after* the publish line. Outside a transaction it fires immediately.
+
+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`.
+
+<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(…)`
+in a plain `async (input, ctx) => { … }` handler works too and resolves with the
+same result. It used to hand back an unrun Effect: nothing published, nothing
+errored, and the handler returned success.
+</Callout>
+
+## Consume it
+
+```tsx
+const { missed, status } = useEvent(gameStarted, arenaId ? { arenaId } : null, (payload) => {
+  scene.switchTo('running', payload.gameId)
+})
+```
+
+`payload` is typed from the descriptor — a wrong field name is a `tsc` error at this call site.
+
+Everything you would otherwise hand-roll is gone, and each of these was a real bug in apps that built this on a reactive list:
+
+- **No history on mount.** A fresh subscriber gets what happens *from now on*. No `seen` set, no `initialized` flag, no window.
+- **Exactly once, even under React `StrictMode`** — where every effect runs twice and a naive subscription fires each handler twice, in development only.
+- **A changing handler does not resubscribe.** Every call site passes an inline arrow; putting it in a dependency array rebuilds the subscription on every render and loses whatever arrives in the gap.
+- **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.
+
+## 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.
+- **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
+
+When deliveries are lost, you are told **how many** and **why**:
+
+```tsx
+useEvent(gameStarted, key, handler, {
+  onMissed: ({ count, reason }) => resyncFromServer(count),   // reason: 'buffer' | 'resume'
+})
+```
+
+Every delivery carries a serial, and the server keeps the highest it has seen — so a loss is arithmetic (what you were owed, minus what could be replayed), never an estimate. `buffer` means your client fell behind and the oldest were dropped; `resume` means a reconnect asked for messages older than the server still holds.
+
+This matters more than it sounds. Silence is the one outcome nothing can be built on: a display cannot tell "no game started" from "I missed the start signal".
+
+### Reconnects resume; mounts do not
+
+These read as one contradiction — *never replay history* against *never lose a message* — and they are two different questions:
+
+- **A first attach** starts empty. Set `rewind: true` on the descriptor if you want the recent buffer instead.
+- **A reconnect** continues from the last serial that subscription saw. `useEvent` does this for you, including after a deploy or a proxy timeout.
+
+The buffer is deliberately small — tens of messages, minutes. Anything larger is a durable queue, and the framework already has one.
+
+## Triggering a workflow from an event
+
+```ts
+triggerWorkflow({ on: gameStarted, workflow: 'postGameReport' })
+```
+
+`on:` takes the descriptor and reads its name, so renaming the event moves this call site with it. The older string form (`event: 'games.started'`) still works and is going away: with a string, a rename leaves the trigger matching nothing and the workflow simply never runs again — nothing errors, which is the same silence this whole primitive exists to remove.
+
+## Reaching HTTP receivers too
+
+An event can also be delivered to subscribed webhook targets — the third audience of the same declaration:
+
+```ts
+export const orderPaid = defineEvent({
+  name: 'orders.paid',
+  key: Schema.Struct({ orderId: Schema.String }),
+  payload: Schema.Struct({ total: Schema.Number }),
+  webhook: { description: 'An order was paid', version: 2 },
+})
+```
+
+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.
+
+## Across instances
+
+Local delivery always works. For fan-out across replicas the event rides postgres `LISTEN/NOTIFY` or [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) (Redis / NATS), exactly like change events — and a broker outage degrades cross-replica delivery without touching local subscribers.
+
+**Each declared event gets its own channel** (`<namespace>:events:<name>`, where
+the namespace defaults to your app's name — see
+[broadcast](/docs/plugins/broadcast)), and a
+replica subscribes to it only while it actually has a local subscriber. This
+matters as soon as one event is much busier than the others: on a single shared
+channel every replica receives, decodes and tracks every event of every peer,
+including the ones it serves no clients for. With five replicas and a high-rate
+event whose subscribers all sit on one of them, four were doing that work and
+discarding the result.
+
+Nothing to configure — it follows from the declaration. The one operational
+consequence: during a **rolling deploy** replicas on different framework versions
+use different channel names, so cross-replica delivery is degraded for the length
+of the rollout. Local delivery on each replica is unaffected throughout.
+
+## Throughput — the numbers, and where this is the wrong primitive
+
+Measured on one core, publish path only:
+
+| | |
+| --- | --- |
+| `bus.publish`, 1–100 subscribers | ~1.5µs (**~670,000/s**) |
+| `bus.publish`, 1000 subscribers | ~3.1µs (~325,000/s) |
+| `ctx.events.publish` (validation + size gate + bus) | ~4.1µs (**~240,000/s**) |
+
+**Across replicas**, measured over a real Redis with two processes — 200 of 200
+delivered, no loss:
+
+| p50 | p95 | p99 | max |
+| --- | --- | --- | --- |
+| 1.67 ms | 2.91 ms | 6.58 ms | 9.95 ms |
+
+That is the broker round trip plus both bus hops. It is the number that matters
+for a display in another pod, and it is the one to compare against a hosted
+realtime service — where the same hop is a network round trip to someone else's
+region.
+
+**Fan-out is nearly free.** One subscriber and a hundred cost the same — the
+per-publish work dominates, not the delivery loop. What you pay per subscriber is
+the wire encode on its own subscription, not anything in the bus.
+
+For a game lifecycle — eight stage events per game, one publish each — that is
+several orders of magnitude of headroom. Even 100 players at 60Hz (6,000
+events/s) sits at ~2.5% of one core.
+
+### Where it stops being the right tool
+
+Not at a throughput number, but at a **semantic** one: this primitive guarantees
+at-most-once delivery of *every* message, with gap accounting. For a 60Hz stream
+of positions or cursors, that guarantee costs something and buys nothing —
+**nobody needs frame 1 once frame 2 has arrived.** You want last-value-wins state,
+not a delivery log.
+
+### `delivery: 'latest'` — when only the current value matters
+
+Declare it, and the framework stops treating a superseded value as a loss:
+
+```ts
+export default defineEvent({
+  name: 'player.moved',
+  key: Schema.Struct({ arenaId: Schema.String }),
+  payload: Schema.Struct({ playerId: Schema.String, x: Schema.Number, y: Schema.Number }),
+  access: 'authenticated',
+  delivery: 'latest',
+})
+```
+
+| | `each` (default) | `latest` |
+| --- | --- | --- |
+| A slow subscriber | keeps the newest, is told how many it lost | receives the current value |
+| Gap reporting | `missed` is computed and delivered | none — nothing was lost |
+| Server retention | up to 64 messages / 5 minutes | one value |
+| Reconnect | replays what is retained, reports the shortfall | hands over the current value |
+
+The distinction is **semantic, not performance**. `latest` is not "the fast mode":
+it changes what a missing message *means*. Choosing it for a stream where each
+delivery matters drops the ones in between; choosing `each` for a per-frame
+stream makes a slow client work through a backlog to reach a state it could have
+had immediately, and report a "loss" that was never one.
+
+The test: **would a consumer be wrong to miss one?**
+
+<Callout type="warn">
+`delivery: 'latest'` cannot be combined with `webhook`, and the declaration is
+refused. `latest` says a superseded delivery did not matter — but a webhook
+delivery is a durable side effect at a third party, and one already sent cannot
+be superseded. A 60Hz event with an HTTP audience is also 60 deliveries per
+second *per subscribed target*, and the webhook rate limit **defers** the excess
+as pending rows rather than dropping it, so the symptom is a growing table rather
+than an error anyone would look at. Publish the high-rate event for clients and a
+separate, coarser one for the outside world.
+</Callout>
+
+### Still worth avoiding
+
+- **Payloads over a few hundred bytes at high rate.** The size gate stops you at
+  7,500 bytes, and long before that the wire encode per subscriber becomes the
+  cost. Send a reference.
+- **Per-frame data as an event at all.** Even under `latest`, 60Hz of positions
+  is 60 encodes per second per subscriber. Coalescing on the client and
+  publishing at 10–20Hz is usually indistinguishable to a human and an order of
+  magnitude cheaper.
+
+The honest rule: **use an event when a consumer would be wrong to miss one.** If
+missing one is fine because the next one supersedes it, either declare
+`delivery: 'latest'` or model it as state — a table, or a value the client
+replaces.
+
+## Testing
+
+```ts
+import { testEventBus } from '@voltro/testing'
+
+const events = testEventBus()
+const display = events.subscribe(gameStarted, { arenaId: 'a1' })
+await events.publish(gameStarted, { arenaId: 'a1' }, { gameId: 'g1', gameType: 'evo5', startedAt: 0 })
+expect(display.received).toEqual([{ gameId: 'g1', gameType: 'evo5', startedAt: 0 }])
+
+// Force a loss deterministically instead of racing a queue:
+events.skipSerials(gameStarted, { arenaId: 'a1' }, 5)
+```
+
+It drives the real bus and the real publish path — validation, the size gate and serials all behave as they do in production — so a test cannot pass on a payload the server would reject.
+
+## Evolving a payload
+
+Clients decode against **their own** copy of the schema. Adding a field is safe. **Removing a required field breaks clients still running the old bundle**, loudly, at decode time — which is better than a silent `undefined` in a handler, and worth knowing if you ship to devices that do not reload for months. Treat those deployments as additive-only.
+
+## Anti-pattern: events as rows
+
+If you have this, replace it:
+
+```tsx
+// ✗ an events TABLE, reconstructed into "new" on the client
+const { data } = useSubscription('app', 'realtime.list', { limit: 500 })
+const seen = useRef(new Set()); const initialized = useRef(false)
+useEffect(() => { /* mark everything seen on the first pass, then diff */ }, [data])
+```
+
+Three bugs in nine lines, and every consumer has to get all three right: the `seen` set, the `initialized` flag (without it, loading the page replays 500 old events into a live system), and `limit` (a silent ceiling — nothing tells you when more than 500 arrive between renders). The table also grows forever and holds rows nobody reads twice.
+
+Migrating is mechanical: declare the event, replace the insert with `ctx.events.publish`, replace the hook with `useEvent`, and drop the table.
+
+## See also
+
+[Subscriptions](/docs/data/subscriptions) · [Outbox](/docs/data/outbox) · [Subscribers](/docs/data/subscribers) · [Streams](/docs/data/streams)
+
+
+
 ---
 
 <!-- source: en/data/rest-routes.md -->
@@ -2123,171 +2447,6 @@ When no analytics sink is configured the framework provides the no-op sink: the
 
 
 
----
-
-<!-- source: en/data/client-state.md -->
-## Client state (defineStore)
-
-_defineStore — client state that is not server state. Selector-only reads, key scoping instead of providers, and SSR seeding that rides the payload the router already writes._
-
-Server state already has a home: a subscription **is** live server state, and it stays live. What has no home is the rest — which rows are selected, which wizard step you are on, the draft you have not submitted.
-
-Without a primitive for that you reach for zustand or jotai, which is a *parallel runtime* — the one thing the framework asks you not to bring. So it ships one.
-
-```ts
-// wizard.store.ts
-import { defineStore } from '@voltro/client'
-
-export const wizard = defineStore('wizard', () => ({ step: 0, draft: '' }))
-```
-
-```tsx
-const step = wizard.use((s) => s.step)                    // the global instance
-const step = wizard.use((s) => s.step, { key: orderId })  // one instance per order
-
-wizard.set({ step: 2 })
-wizard.set((s) => ({ ...s, step: s.step + 1 }))
-```
-
-## Reads go through a selector — there is no `useStore()`
-
-A component that holds the whole state re-renders on every change to any field, so an API that hands it over would be used and would be wrong. Reading a slice re-renders only when **that slice** changes:
-
-```tsx
-const coupon = wizard.use((s) => s.coupon)   // set({ note }) does not re-render this
-const count  = cart.use((s) => s.items.length) // ['a'] → ['b'] does not re-render this
-```
-
-### Computed values need `equals: shallow`
-
-A selector that *builds* something — an object literal, a mapped or filtered array — returns a fresh reference every call, so the default identity check reports "changed" forever and the component re-renders on **every** store change:
-
-```tsx
-import { shallow } from '@voltro/client'
-
-const visible = cart.use((s) => s.items.filter((i) => i.visible), { equals: shallow })
-const pair    = cart.use((s) => ({ a: s.a, b: s.b }), { equals: shallow })
-```
-
-You do not have to remember: in dev the framework detects the case and warns once, naming the fix. The selector is also memoised — it does not re-run while the state object is unchanged, so an expensive filter costs nothing on unrelated updates.
-
-## Scoping is by key, not by a Provider
-
-A Provider re-renders every consumer when its value identity changes, whether or not that consumer read the field that moved — that *is* what makes context painful at scale. So an instance is addressed by a key you already have:
-
-```tsx
-wizard.use((s) => s.step, { key: orderId })
-```
-
-which is the same model as everywhere else in the framework: `useSubscription('orders.list', { orgId })` is keyed by input, not by position in the tree. One read form, an optional key, no provider to forget.
-
-`wizard.release(orderId)` drops an instance; `wizard.keys()` lists the live ones.
-
-## SSR seeding adds no new channel
-
-Call `seedStore` anywhere on the server during a render and the value reaches the client's first render:
-
-```ts
-export const loader = async ({ params }) => {
-  seedStore(wizard, { step: 2 }, { key: params.orderId })
-  return { /* … */ }
-}
-```
-
-There is no `dehydrate()` to remember and no `hydrate()` to forget — the seed rides the hydration payload the router already writes, and `mount()` applies it before the tree exists. A step you can forget is a step somebody will.
-
-On the client `seedStore` **throws**. A silent no-op would leave the store empty in the browser and full on the server, and that surfaces as a hydration mismatch that reads like a React bug.
-
-**The key is part of the address.** Seed with `{ key: orderId }` and read with `{ key: orderId }`. A component reading the global instance while a loader seeded a key gets the initial value — correct, and easy to trip over once.
-
-## Surviving a reload
-
-`persist` writes the state to `localStorage` (or `sessionStorage`) on every change and reads it back when the store is defined:
-
-```tsx
-export const filters = defineStore(
-  'inbox:filters',
-  () => ({ status: 'open', sort: 'newest', draft: '' }),
-  {
-    persist: {
-      key: 'inbox:filters',
-      storage: 'local',              // 'session' lasts the tab
-      pick: (s) => ({ status: s.status, sort: s.sort }),
-      migrate: (stored) => (isFilters(stored) ? stored : undefined),
-    },
-  },
-)
-```
-
-Three details are the whole reason this is in the framework rather than in your codebase, because a hand-rolled version gets all three wrong:
-
-**The stored value is merged over `initial()`, not substituted for it.** Ship a new field and every returning user has state without it — `undefined` where the type promises a string. Merging means an old payload gains the new defaults.
-
-**`migrate` returning `undefined` discards the value.** A stale draft is an annoyance; a half-migrated one is a bug report nobody can reproduce. Discarding is the right answer far more often than guessing, so it is the easy one to write.
-
-**Every storage touch is guarded and wrapped.** The module is imported by the server render too, and Safari in private mode throws on *reading* `localStorage`, not just on writing. A store that throws at import time takes the page with it.
-
-**A persisted store on a server-rendered page hydrates against the *server* value.** The server has no `localStorage`, so it renders `initial()`; the stored value lands in the commit right after hydration. Without that, every returning user would get a hydration mismatch — a flash and a console error that reads like a React bug. `get()` is not deferred, only the render: an action reading the draft before the first paint reads the draft.
-
-`pick` narrows what gets written — persist the filters, not the open/closed state of every panel. And only the **global** instance persists: a keyed instance is per entity, and writing every key into one bucket grows without bound. Persist a map yourself if you mean to.
-
-## Actions that write more than once
-
-An action rarely touches one field. Applying a coupon writes the coupon *and* the recomputed total; that is one thing the user did, and `batch` says so:
-
-```ts
-checkout.batch('applyCoupon', () => {
-  checkout.set({ coupon })
-  checkout.set({ total: recompute(coupon) })
-})
-```
-
-One notification, one entry in the devtools feed named `applyCoupon`, and **one undo step**. Without it the same action is three of each — Ctrl-Z walks back through a third of a change at a time, and the feed shows three anonymous writes instead of the thing that happened. React batches the re-*renders* on its own; it cannot batch the meaning.
-
-**If the callback throws, every write it made is rolled back.** Nothing was announced yet, so an action that fails halfway cannot leave the half-applied state that is the usual reason people reach for a transaction. A nested `batch` joins its parent rather than opening a second one.
-
-### Async work goes around the batch, not inside it
-
-```ts
-const quote = await fetchQuote(coupon)          // await FIRST
-checkout.batch('applyCoupon', () => {           // then batch the writes
-  checkout.set({ coupon, total: quote.total })
-})
-```
-
-Passing an `async` function to `batch` is an **error**, not a warning. Everything after the first `await` would run outside the batch — writes escaping one at a time, a rollback covering only the synchronous head, and a devtools entry that lies about what the action did. Holding a batch open across time is not available: it would have to block every other write for the duration.
-
-## Undo and redo
-
-Every write passes through one seam, so the previous state is already recorded — undo is a lookup rather than a feature the store had to be designed around:
-
-```tsx
-draft.undo(orderId)      // back one write
-draft.redo(orderId)      // forward again
-draft.canUndo(orderId)   // for disabling the button
-draft.canRedo(orderId)
-```
-
-It is a cursor over an intact history, not a stack that consumes entries. So repeated calls walk back through the steps rather than toggling between the last two, and a **new write after an undo drops the redo tail** — the behaviour every editor has.
-
-An undo never becomes undoable itself, and each keyed instance has its own history.
-
-## Devtools: inspect, and travel
-
-The `voltro dev` overlay has a **Stores** tab. It lists every defined store with its live state — global and per key — and a feed of every write: which store, which key, the label if you passed one, and the fields that actually changed.
-
-`◀ Back` and `Forward ▶` step through that feed, restoring the state as it was before or after each write. The state a component reads moves with it, so you can walk back to the moment before a bug and watch it happen again.
-
-No extension, no connector, no version to match. Every write already passes through one seam, so the panel is just another subscriber — it sees writes made by code that never heard of devtools, on any machine, including a colleague's.
-
-## What a store must never hold
-
-Server data. Copying a subscription's rows into a store gives you a second copy that does not live; the page then renders the stale one, and the bug presents as *"reactivity is broken"*. `voltro doctor` reports a `*.store.ts` that reads a subscription.
-
-Read server state where you render it, and keep the store for what is genuinely client-side.
-
-
-
 ---
 
 <!-- source: en/data/crud.md -->
@@ -2735,6 +2894,171 @@ into the agent's prompt.
 
 
 
+---
+
+<!-- source: en/data/client-state.md -->
+## Client state (defineStore)
+
+_defineStore — client state that is not server state. Selector-only reads, key scoping instead of providers, and SSR seeding that rides the payload the router already writes._
+
+Server state already has a home: a subscription **is** live server state, and it stays live. What has no home is the rest — which rows are selected, which wizard step you are on, the draft you have not submitted.
+
+Without a primitive for that you reach for zustand or jotai, which is a *parallel runtime* — the one thing the framework asks you not to bring. So it ships one.
+
+```ts
+// wizard.store.ts
+import { defineStore } from '@voltro/client'
+
+export const wizard = defineStore('wizard', () => ({ step: 0, draft: '' }))
+```
+
+```tsx
+const step = wizard.use((s) => s.step)                    // the global instance
+const step = wizard.use((s) => s.step, { key: orderId })  // one instance per order
+
+wizard.set({ step: 2 })
+wizard.set((s) => ({ ...s, step: s.step + 1 }))
+```
+
+## Reads go through a selector — there is no `useStore()`
+
+A component that holds the whole state re-renders on every change to any field, so an API that hands it over would be used and would be wrong. Reading a slice re-renders only when **that slice** changes:
+
+```tsx
+const coupon = wizard.use((s) => s.coupon)   // set({ note }) does not re-render this
+const count  = cart.use((s) => s.items.length) // ['a'] → ['b'] does not re-render this
+```
+
+### Computed values need `equals: shallow`
+
+A selector that *builds* something — an object literal, a mapped or filtered array — returns a fresh reference every call, so the default identity check reports "changed" forever and the component re-renders on **every** store change:
+
+```tsx
+import { shallow } from '@voltro/client'
+
+const visible = cart.use((s) => s.items.filter((i) => i.visible), { equals: shallow })
+const pair    = cart.use((s) => ({ a: s.a, b: s.b }), { equals: shallow })
+```
+
+You do not have to remember: in dev the framework detects the case and warns once, naming the fix. The selector is also memoised — it does not re-run while the state object is unchanged, so an expensive filter costs nothing on unrelated updates.
+
+## Scoping is by key, not by a Provider
+
+A Provider re-renders every consumer when its value identity changes, whether or not that consumer read the field that moved — that *is* what makes context painful at scale. So an instance is addressed by a key you already have:
+
+```tsx
+wizard.use((s) => s.step, { key: orderId })
+```
+
+which is the same model as everywhere else in the framework: `useSubscription('orders.list', { orgId })` is keyed by input, not by position in the tree. One read form, an optional key, no provider to forget.
+
+`wizard.release(orderId)` drops an instance; `wizard.keys()` lists the live ones.
+
+## SSR seeding adds no new channel
+
+Call `seedStore` anywhere on the server during a render and the value reaches the client's first render:
+
+```ts
+export const loader = async ({ params }) => {
+  seedStore(wizard, { step: 2 }, { key: params.orderId })
+  return { /* … */ }
+}
+```
+
+There is no `dehydrate()` to remember and no `hydrate()` to forget — the seed rides the hydration payload the router already writes, and `mount()` applies it before the tree exists. A step you can forget is a step somebody will.
+
+On the client `seedStore` **throws**. A silent no-op would leave the store empty in the browser and full on the server, and that surfaces as a hydration mismatch that reads like a React bug.
+
+**The key is part of the address.** Seed with `{ key: orderId }` and read with `{ key: orderId }`. A component reading the global instance while a loader seeded a key gets the initial value — correct, and easy to trip over once.
+
+## Surviving a reload
+
+`persist` writes the state to `localStorage` (or `sessionStorage`) on every change and reads it back when the store is defined:
+
+```tsx
+export const filters = defineStore(
+  'inbox:filters',
+  () => ({ status: 'open', sort: 'newest', draft: '' }),
+  {
+    persist: {
+      key: 'inbox:filters',
+      storage: 'local',              // 'session' lasts the tab
+      pick: (s) => ({ status: s.status, sort: s.sort }),
+      migrate: (stored) => (isFilters(stored) ? stored : undefined),
+    },
+  },
+)
+```
+
+Three details are the whole reason this is in the framework rather than in your codebase, because a hand-rolled version gets all three wrong:
+
+**The stored value is merged over `initial()`, not substituted for it.** Ship a new field and every returning user has state without it — `undefined` where the type promises a string. Merging means an old payload gains the new defaults.
+
+**`migrate` returning `undefined` discards the value.** A stale draft is an annoyance; a half-migrated one is a bug report nobody can reproduce. Discarding is the right answer far more often than guessing, so it is the easy one to write.
+
+**Every storage touch is guarded and wrapped.** The module is imported by the server render too, and Safari in private mode throws on *reading* `localStorage`, not just on writing. A store that throws at import time takes the page with it.
+
+**A persisted store on a server-rendered page hydrates against the *server* value.** The server has no `localStorage`, so it renders `initial()`; the stored value lands in the commit right after hydration. Without that, every returning user would get a hydration mismatch — a flash and a console error that reads like a React bug. `get()` is not deferred, only the render: an action reading the draft before the first paint reads the draft.
+
+`pick` narrows what gets written — persist the filters, not the open/closed state of every panel. And only the **global** instance persists: a keyed instance is per entity, and writing every key into one bucket grows without bound. Persist a map yourself if you mean to.
+
+## Actions that write more than once
+
+An action rarely touches one field. Applying a coupon writes the coupon *and* the recomputed total; that is one thing the user did, and `batch` says so:
+
+```ts
+checkout.batch('applyCoupon', () => {
+  checkout.set({ coupon })
+  checkout.set({ total: recompute(coupon) })
+})
+```
+
+One notification, one entry in the devtools feed named `applyCoupon`, and **one undo step**. Without it the same action is three of each — Ctrl-Z walks back through a third of a change at a time, and the feed shows three anonymous writes instead of the thing that happened. React batches the re-*renders* on its own; it cannot batch the meaning.
+
+**If the callback throws, every write it made is rolled back.** Nothing was announced yet, so an action that fails halfway cannot leave the half-applied state that is the usual reason people reach for a transaction. A nested `batch` joins its parent rather than opening a second one.
+
+### Async work goes around the batch, not inside it
+
+```ts
+const quote = await fetchQuote(coupon)          // await FIRST
+checkout.batch('applyCoupon', () => {           // then batch the writes
+  checkout.set({ coupon, total: quote.total })
+})
+```
+
+Passing an `async` function to `batch` is an **error**, not a warning. Everything after the first `await` would run outside the batch — writes escaping one at a time, a rollback covering only the synchronous head, and a devtools entry that lies about what the action did. Holding a batch open across time is not available: it would have to block every other write for the duration.
+
+## Undo and redo
+
+Every write passes through one seam, so the previous state is already recorded — undo is a lookup rather than a feature the store had to be designed around:
+
+```tsx
+draft.undo(orderId)      // back one write
+draft.redo(orderId)      // forward again
+draft.canUndo(orderId)   // for disabling the button
+draft.canRedo(orderId)
+```
+
+It is a cursor over an intact history, not a stack that consumes entries. So repeated calls walk back through the steps rather than toggling between the last two, and a **new write after an undo drops the redo tail** — the behaviour every editor has.
+
+An undo never becomes undoable itself, and each keyed instance has its own history.
+
+## Devtools: inspect, and travel
+
+The `voltro dev` overlay has a **Stores** tab. It lists every defined store with its live state — global and per key — and a feed of every write: which store, which key, the label if you passed one, and the fields that actually changed.
+
+`◀ Back` and `Forward ▶` step through that feed, restoring the state as it was before or after each write. The state a component reads moves with it, so you can walk back to the moment before a bug and watch it happen again.
+
+No extension, no connector, no version to match. Every write already passes through one seam, so the panel is just another subscriber — it sees writes made by code that never heard of devtools, on any machine, including a colleague's.
+
+## What a store must never hold
+
+Server data. Copying a subscription's rows into a store gives you a second copy that does not live; the page then renders the stale one, and the bug presents as *"reactivity is broken"*. `voltro doctor` reports a `*.store.ts` that reads a subscription.
+
+Read server state where you render it, and keep the store for what is genuinely client-side.
+
+
+
 ---
 
 <!-- source: en/data/outbox.md -->