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

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; }