@spfn/core 0.3.0-beta.27 → 0.3.0-beta.29

package/dist/{types-CqTsDETV.d.ts → types-DncqXfWN.d.ts}

@@ -1,5 +1,5 @@
 import { Context } from 'hono';
-import { a as EventDef, n as EventRouterBase, I as InferEventNames, i as InferEventPayload } from './router-D5B0cpVN.js';
+import { a as EventDef, o as EventRouterBase, I as InferEventNames, i as InferEventPayload } from './router-CX5uVjmU.js';
 import { c as SSETokenStore, S as SSETokenManager } from './token-manager-Ckjt2-qq.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.27",
+    "version": "0.3.0-beta.29",
     "description": "Full-stack TypeScript backend for Next.js: file-based typed routes, Drizzle entities and repositories, PostgreSQL transactions and a generated end-to-end client, in one fixed vertical slice per feature",
     "type": "module",
     "exports": {

package/src/codegen/README.md

@@ -52,14 +52,16 @@ Types:
 - `OrchestratorOptions`
 - `RouteMapGeneratorConfig` (config shape for the built-in route-map generator)
 - `ContractGeneratorConfig` (config shape for the built-in contract generator)
-- `ContractGeneratorError`, `ConditionalRegistrationError`, `assertUnconditionalRegistration`
+- `StatesGeneratorConfig` (config shape for the built-in states generator)
+- `ContractGeneratorError`, `StatesGeneratorError`, `ConditionalRegistrationError`,
+  `assertUnconditionalRegistration`
 - `RouteContractMapping`, `ResourceRoutes`, `ClientGenerationOptions`, `GenerationStats`
   (legacy client-generation types — exported but not used by any shipped generator)
 
 > **Renamed: `defineCodegenConfig` → `defineConfig`.** The old name does **not** exist.
 > Older docs also show an `api-client` / `createApi`-emitting generator and
 > `codegen.config.ts` — those are **removed**. The built-in generators today are
-> `@spfn/core:route-map` and `@spfn/core:contract`, configured in `.spfnrc.ts`. Do not
+> `@spfn/core:route-map`, `@spfn/core:contract` and `@spfn/core:states`, configured in `.spfnrc.ts`. Do not
 > import `defineCodegenConfig` or configure a `name: 'api-client'` generator.
 
 ---
@@ -320,6 +322,83 @@ make the feature unusable.
 
 ---
 
+## Built-in: `@spfn/core:states`
+
+Loads your router and emits the ids and the manifest of every state it mounts —
+`src/generated/states.ts`, a file with no import that a browser root and a server component
+can both execute. `createStateClient<typeof states>` is a type import, erased at build, and
+importing the router itself is not an option (each state's `read()` closes over repositories
+and the database), so this file is the only runtime record of which states the app declared.
+Compare its `stateManifest` with the `manifest` of `GET /state`: an id the server's manifest
+lacks is a deploy skew between the Next.js server and the API, reported at the root instead
+of surfacing as `state.<id>` being `undefined` inside a screen. See
+[`../state/README.md`](../state/README.md) → "Declared ids at runtime".
+
+### `StatesGeneratorConfig`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | `'@spfn/core:states'` | yes | — | Generator identifier (literal). |
+| `routerPath` | `string` | yes | — | Router file, relative to project root — the one `route-map` reads. Throws at construction if missing. |
+| `outputPath` | `string` | no | `'./src/generated/states.ts'` | Where the file is written (parent dirs auto-created). |
+
+### What it reads
+
+The router module is loaded exactly as `route-map` loads it (`appRouter` → `default` →
+`router`, tsconfig aliases, `NODE_ENV` pinned), then walked:
+
+- **The marker.** `defineStateRouter` sets a non-enumerable `Router._stateManifest` on the
+  router it derives — the very object the snapshot route answers as `manifest` — so the ids
+  written here and the manifest the server serves come from one value. Each state router
+  contributes its entries in declaration order; `key` lists the key fields in schema order.
+- **Mounted routers at every depth.** Every nested router under `routes` and every entry of
+  `_packageRouters`, recursively — app `routes` first, then `_packageRouters` in mount order.
+  A router reached by two trails (`.packages()` copies a mounted router's own package routers
+  up) is collected once: the walk is keyed on the router object.
+- **Chained routers.** `.use()`, `.packages()` and `.contractVersion()` carry the marker onto
+  the router they rebuild, so `states.router.use([audit])` is still found.
+- An id that is not a JS identifier is emitted quoted, through the same key rule `route-map`
+  uses.
+
+### When it refuses
+
+Throws `StatesGeneratorError` (or the loader's and the guard's errors) — logged on `watch`,
+fatal on `build` and on `spfn codegen run`:
+
+- The module will not load, or no router is found under the three export names.
+- The router registers **conditionally** — same `ConditionalRegistrationError` guard as
+  `route-map`.
+- **Two state routers declare the same id.** The message names both trails.
+- **No state router is mounted** anywhere in the walk. The generator is configured but nothing
+  it reads mounts a `defineStateRouter(...).router`; the message names the router path. Mount
+  the state router or drop the generator.
+
+A mounted state router that declares **no state** — `defineStateRouter({})` — is not refused: it
+is an app that has declared none yet. The file is written with `stateIds = [] as const` and an
+empty `stateManifest`, which matches the empty manifest the server serves.
+
+A **missing router file** is only a warning: the generator returns and writes nothing.
+
+### Generated output
+
+```typescript
+// src/generated/states.ts  — DO NOT EDIT (header names the NODE_ENV it was written under)
+export const stateIds = ['consent', 'member', 'workspaces'] as const;
+
+export type StateId = (typeof stateIds)[number];
+
+export const stateManifest: Readonly<Record<StateId, { readonly key: readonly string[]; readonly write: boolean }>> = {
+    consent: { key: [], write: true },
+    member: { key: ['workspaceId'], write: false },
+    workspaces: { key: [], write: false },
+};
+```
+
+`watchPatterns` are `[routerPath, 'src/server/states.ts', 'src/server/states/**/*.ts',
+'src/server/routes/**/*.ts']` and `runOn` is `['watch', 'manual', 'build']`.
+
+---
+
 ## CLI
 
 Provided by the `spfn` CLI (`@spfn/cli`), not by `@spfn/core` itself:
@@ -625,10 +704,18 @@ interface RouteMapGeneratorConfig
     outputPath?: string;               // default './src/generated/route-map.ts'
     additionalRouteDirs?: string[];   // deprecated: watched, never collected from
 }
+
+interface StatesGeneratorConfig
+{
+    name: '@spfn/core:states';
+    routerPath: string;
+    outputPath?: string;               // default './src/generated/states.ts'
+}
 ```
 
 ## Related
 
 - [@spfn/core/route](../route/README.md) — `route.*` / `defineRouter` (the router loaded and walked)
 - [@spfn/core/nextjs](../nextjs/README.md) — RPC proxy (`createRpcProxy`) that consumes `routeMap`
+- [@spfn/core/state](../state/README.md) — `defineStateRouter`, whose manifest `@spfn/core:states` writes
 - [@spfn/core/env](../env/README.md) — environment configuration

package/src/db/transaction/README.md

@@ -44,7 +44,7 @@ From `@spfn/core/db`:
 - `runInTransaction(callback, options?)` — run a callback in a transaction (scripts/CLI; no Hono).
 - `onBeforeCommit(callback)` — run work inside the root transaction, just before it commits.
 - `onAfterCommit(callback)` — defer a side effect until after the root transaction commits.
-- `onAfterRollback(callback)` — compensate after the root transaction rolled back.
+- `onAfterRollback(callback)` — compensate after the work it was registered with rolled back.
 - `getTransaction()` — current transaction `TransactionDB`, or `null`.
 - `getTransactionContext()` — current `TransactionContext` (`tx`, `txId`, `level`, callbacks), or `null`.
 - `runWithTransaction(tx, txId, callback)` — bind a `tx` into `AsyncLocalStorage` for a callback.
@@ -305,9 +305,12 @@ Behavior to know:
   against a row the outer transaction locked.
 - **One commit.** Nested writes are durable only when the **root** commits. There is no
   intermediate commit at a savepoint boundary.
-- The inner level shares **all three of the root's** hook queues, so a hook registered in
-  a nested call fires at the **root's** boundary, not the savepoint's. See
-  [Transaction hooks](#transaction-hooks).
+- The inner level has **hook queues of its own**: a hook belongs to the savepoint that
+  registered it. A savepoint that resolves hands its hooks to its parent; one that rolls
+  back runs its `onAfterRollback` callbacks right there — inside the **parent's** context,
+  the root still open — and drops its `onBeforeCommit` / `onAfterCommit` callbacks, even
+  when the root goes on to commit. See
+  [Hooks belong to the frame that registered them](#hooks-belong-to-the-frame-that-registered-them).
 - **One at a time.** Nested calls made off the same transaction are serialized: a frame
   opens only after the previous frame on that connection has closed. See
   [Concurrent nested calls](#concurrent-nested-calls-are-serialized).
@@ -453,23 +456,25 @@ logging the SQL it emits — worth knowing before nesting deeply or in a loop:
 
 ## Transaction hooks
 
-Three hooks attach work to the **root** transaction's lifecycle. All three take
+Three hooks attach work to a transaction's lifecycle. All three take
 `() => void | Promise<void>`, are registered the same way from anywhere inside the async
-call chain, and queue on the root context (`BeforeCommitCallback`, `AfterCommitCallback`,
-`AfterRollbackCallback` are the exported type aliases).
+call chain, and queue on the **frame** — root or savepoint — they were registered in
+(`BeforeCommitCallback`, `AfterCommitCallback`, `AfterRollbackCallback` are the exported
+type aliases). A frame's queues reach the root only through savepoints that resolved; see
+[Hooks belong to the frame that registered them](#hooks-belong-to-the-frame-that-registered-them).
 
 | Hook | Runs | Still inside the tx? | If the callback throws |
 |------|------|----------------------|------------------------|
 | `onBeforeCommit(cb)` | after the root callback resolves, **before** `COMMIT` | **yes** — may run statements | aborts: later callbacks skipped, transaction rolls back, error propagates, `afterRollback` fires |
 | `onAfterCommit(cb)` | after the root transaction committed | no | logged, never thrown |
-| `onAfterRollback(cb)` | after the root transaction rolled back | no | logged, never thrown; the **original** error keeps propagating unchanged |
+| `onAfterRollback(cb)` | after the root transaction rolled back — or, registered in a savepoint that rolled back, right after that savepoint did | no after a root rollback; after a savepoint rollback it runs inside the **parent's** still-open transaction | logged, never thrown; the **original** error keeps propagating unchanged |
 
 Registration context:
 
 | Context | `onBeforeCommit` | `onAfterCommit` | `onAfterRollback` |
 |---------|------------------|-----------------|-------------------|
 | Inside root transaction | Queued; runs before the root's commit | Queued; runs after the root commits | Queued; runs if the root rolls back |
-| Inside a nested transaction | Queued on the **root** queue | Queued on the **root** queue | Queued on the **root** queue |
+| Inside a nested transaction | Queued on the savepoint; passed to the parent if it resolves, dropped if it rolls back | Queued on the savepoint; passed to the parent if it resolves, dropped if it rolls back | Queued on the savepoint; passed to the parent if it resolves, **run at once** if it rolls back |
 | Outside any transaction | Runs immediately on a microtask **+ `warn` log** — nothing left to commit, so a throw aborts nothing | Runs immediately on a microtask (already "committed") | **No-op + `warn` log** — there is no rollback to wait for |
 
 ### `onBeforeCommit(callback)`
@@ -567,11 +572,16 @@ async function importAvatar(userId: string, file: Blob)
 
 - Fires on **any** root rollback: a thrown handler error, a thrown `onBeforeCommit`
   callback, a statement timeout, a constraint violation.
-- Callbacks run **outside** the transaction context (`getTransaction()` is `null`), after
-  the driver rolled back — DB work in them uses a fresh connection, like `onAfterCommit`.
+- Registered inside a savepoint, it fires when **that savepoint** rolls back — at that
+  moment, whatever the root does afterwards — and not again at the root.
+- After a **root** rollback, callbacks run **outside** the transaction context
+  (`getTransaction()` is `null`) — DB work in them uses a fresh connection, like
+  `onAfterCommit`. After a **savepoint** rollback the root is still open and they run
+  inside the **parent's** context: `getTransaction()` is the parent's `tx`, and DB work in
+  them joins the parent transaction — it commits only if the parent does.
 - They are **awaited**, in registration order, before the causing error leaves
-  `runInTransaction` / the middleware. A callback that hangs delays that error, so keep
-  them short.
+  `runInTransaction` / the middleware (for a savepoint: the nested call). A callback that
+  hangs delays that error, so keep them short.
 - Errors are logged and swallowed: a failing callback never replaces the error that caused
   the rollback, never stops the remaining callbacks, and neither does a failure of the log
   call itself.
@@ -580,28 +590,41 @@ async function importAvatar(userId: string, file: Blob)
   to the client, and these callbacks fire — so a compensation should be idempotent and
   safe to run against data that did, in the end, land.
 
-### Hooks are scoped to the root transaction
-
-Every queue lives on the root context and nested contexts share it, so the **root's** fate
-decides everything:
-
-- A nested transaction that rolls back while the **root commits** fires **no**
-  `afterRollback` callbacks — not the ones registered nested, not the ones registered at the
-  root. The hooks answer "did the root transaction survive?", and it did. Compensating for a
-  nested failure the outer code deliberately caught and recovered from is that code's job.
-- Conversely, hooks registered in a nested call fire exactly once, at the root's boundary —
-  never once per nesting level.
-- **Registering compensations from a nested call is correct for the root's fate — and only
-  for it.** A nested call is a SAVEPOINT: its writes are durable only if the root commits,
-  so when the nested call *succeeded* and the root later rolls back, an `onAfterRollback`
-  registered inside it fires exactly when the work it compensates for disappears, and stays
-  silent when the root commits that work.
-  It is **not** a general "fires when my writes disappear" hook: in the caught-rollback case
-  above, the nested writes are gone and no hook fires at all. Code that catches a nested
-  failure and carries on must compensate **in the catch block**, at the moment it decides to
-  recover; deferring that to `onAfterRollback` compensates for nothing.
-- A `requiresNew: true` call is the exception, because it is a root: hooks registered inside
-  it belong to it and fire on its own commit or rollback.
+### Hooks belong to the frame that registered them
+
+Every frame — the root and each savepoint — has queues of its own, and its **own** fate
+decides what happens to the hooks registered in it:
+
+- **A savepoint that resolves** appends its three queues to its parent's, after what the
+  parent registered before the nested call and before what it registers after. Its hooks
+  now share the parent's fate: `onBeforeCommit` still runs before the **root's** `COMMIT`
+  (not at the savepoint — the driver never releases one), `onAfterCommit` after the root
+  commits, `onAfterRollback` if the root rolls back. Promotion repeats level by level, so a
+  hook fires exactly once, and only if every savepoint between it and the root resolved.
+- **A savepoint that rolls back** drops its `onBeforeCommit` and `onAfterCommit`
+  callbacks — the work they guard or announce is gone — and runs its `onAfterRollback`
+  callbacks immediately, awaited before the error leaves the nested call, inside the
+  parent's still-open transaction. Hooks promoted into it from savepoints nested inside it
+  go the same way. A compensation may call `runInTransaction` itself: that opens a savepoint
+  on the parent, and a hook the compensation registers belongs to the parent.
+- **A statement that fails inside a savepoint's `onAfterRollback` aborts the parent.** The
+  root-rollback pass runs outside any transaction, so a failing statement there touches
+  nothing; the savepoint pass runs inside the parent's transaction, so a failing statement
+  puts it into the aborted state (`25P02`). The callback's error is logged and swallowed as
+  always, but the root's next statement then fails with `25P02` (current transaction is
+  aborted). If the root runs none, its `COMMIT` fails with the callback's error. Either way,
+  everything the root wrote rolls back. Wrap DB work in a compensation in its own
+  `runInTransaction` (a savepoint) when it may fail.
+- **The root** runs whatever reached it. A savepoint failure the root catches and survives
+  fires none of the **root's** own `afterRollback` callbacks: the root did not roll back.
+- A `requiresNew: true` call is a root on its own connection: hooks registered inside it
+  belong to it and fire on its own commit or rollback, never handed to the outer
+  transaction.
+- **A hook registered after its frame has settled is dropped**, the same as one registered
+  after a root has settled. A frame's queues are handed on (or discarded) once, at the
+  moment it settles; detached work it started — a `setTimeout`, an un-awaited promise —
+  that registers a hook later appends to a queue nobody reads again. Register hooks in the
+  awaited call chain of the frame they belong to.
 
 ### Why there is no `onBeforeRollback`
 

package/src/event/README.md

@@ -45,12 +45,13 @@ From `@spfn/core/event`:
 - `.contract({ since, deprecatedIn?, removedIn? })` on an event and `.contract({ auth, streamPath? })`
   on an event router — publish the event in `contracts/current.json` (see
   [Contracted events](#contracted-events-for-separately-compiled-clients))
-- `.canSubscribe(predicate)`, `.filter(predicate)`, `.grant(subject)`, `.revoke(subject)` on an
-  event — who may subscribe over SSE, which frames a connection receives, and changing an open
-  connection (see [Per-event permission](#per-event-permission-cansubscribe-filter-grant--revoke))
+- `.canSubscribe(predicate)`, `.filter(predicate)`, `.initial(producer)`, `.grant(subject)`,
+  `.revoke(subject)` on an event — who may subscribe over SSE, which frames a connection receives,
+  the frames it receives right after `connected`, and changing an open connection (see
+  [Per-event permission](#per-event-permission-cansubscribe-filter-initial-grant--revoke))
 - Types: `EventDef`, `EventHandler`, `EventSubscribeOptions`, `InferEventPayload`, `PubSubCache`, `JobQueueSender`,
   `EventContract`, `EventRouterContract`, `SubscribePredicate`, `SubscribeContext`,
-  `SubscribeRequest`, `FramePredicate`, `FrameContext`,
+  `SubscribeRequest`, `FramePredicate`, `FrameContext`, `InitialProducer`,
   `EventRouterDef`, `InferEventNames`, `InferEventPayloads`,
   `InferRouterEventPayload` (the two-arg router variant — see note)
 
@@ -61,7 +62,7 @@ From `@spfn/core/event/sse`:
 - Types: `SSEToken`, `SSETokenStore`, `SSETokenManagerConfig`, `SSEMessage`,
   `SSEHandlerConfig`, `SSEHandlerAuthConfig`, `SSEAuthConfig`, `SSEClientConfig`,
   `SSEEventHandler`, `SSEEventHandlers`, `SSESubscribeOptions`, `SSESubscriptionChange`,
-  `SSEConnectionState`, `SSEUnsubscribe`
+  `SSEConnectionState`, `SSEUnsubscribe`, `ConnectedPayload`
 
 From `@spfn/core/event/sse/client`:
 
@@ -139,6 +140,7 @@ Promise<void>` otherwise. Handlers run via `Promise.allSettled` — see
 | `contract(contract)` | `(EventContract) => EventDef` | publish in the contract; returns the same event; a second call throws |
 | `canSubscribe(predicate)` | `<P>(SubscribePredicate<P>) => EventDef` | who may subscribe over SSE (once per connection); a second call throws |
 | `filter(predicate)` | `(FramePredicate<TPayload>) => EventDef` | which frames a connection receives (sync, per frame); a second call throws |
+| `initial(producer)` | `<P>(InitialProducer<TPayload, P>) => EventDef` | the frames a connection receives right after `connected`, before any live frame (once per connection with a subject); a second call throws |
 | `grant(subject, match?)` | `Promise<void>` | activate the event on the subject's open SSE connections (those matching `match`, when given) where it is denied |
 | `revoke(subject, match?)` | `Promise<void>` | deactivate the event on the subject's open SSE connections (those matching `match`, when given) where it is allowed |
 
@@ -274,7 +276,9 @@ Client                              Server
   │                                   │  → authorize(subject, events)
   │                                   │  → resolvePrincipal(subject, request)   (once)
   │                                   │  → event.canSubscribe(ctx)              (once per event)
-  │  ◄═══════════════════════════════ │  SSE stream opens (connected: subscribed + denied)
+  │                                   │  → event.initial(ctx)                   (once per allowed event; live frames held)
+  │  ◄═══════════════════════════════ │  SSE stream opens (connected: subscribed + denied + initial)
+  │  event: <name> / data: {…}        │  ← each initial frame, then the held live frames
   │  event: <name> / data: {…}        │  ← filter(subject, payload) + event.filter(payload, ctx) per emission
 ```
 
@@ -393,7 +397,7 @@ Return `false` to skip. Payload is typed per event.
 })
 ```
 
-### Per-event permission (`canSubscribe`, `filter`, `grant` / `revoke`)
+### Per-event permission (`canSubscribe`, `filter`, `initial`, `grant` / `revoke`)
 
 The global hooks above are one function for the whole router. When the rule belongs to one event,
 declare it where the event is defined:
@@ -403,7 +407,8 @@ export const auditLogged = defineEvent('audit.logged', payload)
     .canSubscribe<AuthPrincipal>(({ subject, principal, request }) => principal?.role === 'admin');
 
 export const runtimeChanged = defineEvent('runtime.changed', payload)
-    .filter((payload, { subject, request }) => payload.workspaceId === request.query.workspaceId);
+    .filter((payload, { subject, request }) => payload.workspaceId === request.query.workspaceId)
+    .initial(async ({ request }) => [await runtimes.current(request.query.workspaceId)]);
 ```
 
 - **`canSubscribe(ctx)`** — once per connection per requested event, only when the connection has a
@@ -414,11 +419,26 @@ export const runtimeChanged = defineEvent('runtime.changed', payload)
 - **`filter(payload, ctx)`** — per frame, with or without a subject; it matches the payload against
   the connect request. It runs beside the global `filter` map — both must return `true`. Sync. A
   throw drops that frame (warn) and leaves the connection alive.
-- **`request`** in both is a snapshot taken once at connect: `{ query, headers }` with lowercased
+- **`initial(ctx)`** — the event's current frames for one connection, written right after the
+  `connected` frame and before any live frame, so a client that opens the stream needs no read of
+  its own. It runs once per connection **with a subject**, only for an event `canSubscribe` allowed,
+  with the same `{ subject, principal, request }`; the producers of one connection run in
+  parallel, and their frames are written in the order the events were requested. It returns an
+  array of payloads (`[]` sends nothing but still counts as served). Its frames skip both filters —
+  they were produced for this connection — so the producer must return only what this subject may
+  see: neither the global `filter` nor `.filter()` runs on its frames. They number their
+  `messageId`s like any frame. The
+  `connected` frame's `initial` lists exactly the events whose producer returned; a producer that
+  throws or rejects is logged at warn with the event name (never the error) and sends nothing,
+  and the stream stays open. While the producers run, live frames — and `grant` / `revoke` frames
+  and pings — are held, then written after the initial frames in arrival order; a `revoke` landing
+  meanwhile still stops the subscription at once. A `grant` later never runs it. A connection
+  without a subject, or with no allowed event that declares it, gets `initial: []`.
+- **`request`** in all three is a snapshot taken once at connect: `{ query, headers }` with lowercased
   header names — never the live Hono context. It is the connect request as sent: it holds the
   `cookie` / `authorization` headers and the consumed one-time `token` in `query`, so the app must
   never log the snapshot.
-- Both are set once per event: an `EventDef` is a shared singleton, so a second call throws.
+- Each is set once per event: an `EventDef` is a shared singleton, so a second call throws.
 
 **`resolvePrincipal` — why the stream has no `AuthContext`.** The subject comes from the one-time
 token, and the stream is mounted without the app's middleware, so there is no request auth object
@@ -441,10 +461,17 @@ resolved' }`.
 kept → per frame, the global `filter` and the event's `filter`. An event `authorize` dropped is
 never asked and counts as denied too.
 
-**Cost.** At connect: one predicate call per requested event (plus one `resolvePrincipal`). Per
-frame: sync filters only — never storage. The handler sets no timeout on them: a hanging
-`canSubscribe` or `resolvePrincipal` holds the connect open, so the app owns the timeout. A
-client that leaves meanwhile is forgotten at once; the late verdict opens nothing.
+**Cost.** At connect: one predicate call per requested event (plus one `resolvePrincipal`), and
+one `initial` producer call per allowed event that declares one. Per frame: sync filters only —
+never storage. The handler sets no timeout on them: a hanging `canSubscribe` or
+`resolvePrincipal` holds the connect open, and a hanging `initial` holds the `connected` frame and
+every live frame behind it, so the app owns the timeout. A client that leaves meanwhile is
+forgotten at once; the late verdict opens nothing, and late initial frames are not written. The
+initial frames and the held live frames go through the connection's bounded queue like any frame:
+a held frame counts against `maxQueue` from the moment it is held, together with the frames
+already queued, and past it the connection is closed as a slow consumer — while the producers
+still run, too — and the client reconnects. A producer's duration thus counts as the client's
+slowness: frames that pile up while it runs count as frames the client has not read.
 
 **`grant` / `revoke` — changing an open connection.**
 
@@ -501,6 +528,22 @@ client.subscribe({
 });
 ```
 
+The `connected` frame — always the first of a connection — carries
+`{ subscribedEvents, deniedEvents, initial, timestamp }` (`ConnectedPayload`; `initial` is absent
+from a server that predates `.initial()`). `onConnected` receives it on every connection, the first
+and each reconnect, after `onOpen`:
+
+```typescript
+client.subscribe({
+    events: ['runtimeChanged'],
+    handlers: { runtimeChanged: (p) => update(p) },
+    onConnected: ({ deniedEvents, initial }) =>
+    {
+        // initial: the events whose current frames follow this one; read the others yourself
+    },
+});
+```
+
 ### SSE auth config (`SSEAuthConfig<TRouter>`)
 
 | Option | Type | Default | Description |
@@ -891,6 +934,8 @@ interface EventDef<TPayload = void> {
     canSubscribe: <P = unknown>(predicate: SubscribePredicate<P>) => EventDef<TPayload>;
     readonly _filter?: FramePredicate<TPayload>;
     filter: (predicate: FramePredicate<TPayload>) => EventDef<TPayload>;
+    readonly _initial?: InitialProducer<TPayload, any>;
+    initial: <P = unknown>(producer: InitialProducer<TPayload, P>) => EventDef<TPayload>;
     grant: (subject: string, match?: SubscriptionMatch) => Promise<void>;
     revoke: (subject: string, match?: SubscriptionMatch) => Promise<void>;
 }
@@ -901,6 +946,8 @@ interface SubscribeContext<P = unknown> { subject: string; principal: P | undefi
 type SubscribePredicate<P = unknown> = (ctx: SubscribeContext<P>) => boolean | Promise<boolean>;
 interface FrameContext { subject: string | undefined; request: SubscribeRequest; }
 type FramePredicate<TPayload> = (payload: TPayload, ctx: FrameContext) => boolean;
+type InitialProducer<TPayload, P = unknown> = (ctx: SubscribeContext<P>) => TPayload[] | Promise<TPayload[]>;
+interface ConnectedPayload { subscribedEvents: string[]; deniedEvents: string[]; initial?: string[]; timestamp: number; }
 
 interface EventContract { since: string; deprecatedIn?: string; removedIn?: string; }