@spfn/core 0.3.0-beta.18 → 0.3.0-beta.19

package/dist/token-manager-Ckjt2-qq.d.ts

@@ -0,0 +1,122 @@
+/**
+ * SSE Token Manager
+ *
+ * Auth-agnostic token issuance and verification for SSE connections.
+ * Issues one-time-use tokens with TTL for Token Exchange pattern.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SSETokenManager({ ttl: 30000 });
+ *
+ * // Issue token for authenticated user
+ * const token = await manager.issue('user-123');
+ *
+ * // Verify and consume token (one-time use)
+ * const subject = await manager.verify(token); // 'user-123'
+ * const again = await manager.verify(token);   // null (already consumed)
+ *
+ * // Cleanup on shutdown
+ * manager.destroy();
+ * ```
+ */
+/**
+ * Minimal cache client interface (compatible with ioredis Redis | Cluster)
+ */
+type CacheClient = {
+    set(key: string, value: string, ...args: any[]): Promise<any>;
+    getdel?(key: string): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+};
+/**
+ * Stored SSE token data
+ */
+interface SSEToken {
+    subject: string;
+    expiresAt: number;
+}
+/**
+ * Token storage interface
+ *
+ * Implement this for custom storage backends (e.g., Redis for multi-instance).
+ */
+interface SSETokenStore {
+    /** Store a token */
+    set(token: string, data: SSEToken): Promise<void>;
+    /** Get and delete a token (one-time use) */
+    consume(token: string): Promise<SSEToken | null>;
+    /** Remove expired tokens */
+    cleanup(): Promise<void>;
+}
+/**
+ * SSETokenManager configuration
+ */
+interface SSETokenManagerConfig {
+    /**
+     * Token time-to-live in milliseconds
+     * @default 30000
+     */
+    ttl?: number;
+    /**
+     * Custom token store (default: in-memory Map)
+     */
+    store?: SSETokenStore;
+    /**
+     * Cleanup interval in milliseconds
+     * @default 60000
+     */
+    cleanupInterval?: number;
+}
+/**
+ * Redis/Valkey-backed token store for multi-instance deployments.
+ *
+ * Uses SET EX for automatic TTL expiry and GETDEL for atomic one-time consumption.
+ * No cleanup needed — Redis handles expiration automatically.
+ *
+ * @example
+ * ```typescript
+ * import { getCache } from '@spfn/core/cache';
+ *
+ * const cache = getCache();
+ * if (cache) {
+ *     const store = new CacheTokenStore(cache);
+ *     const manager = new SSETokenManager({ store });
+ * }
+ * ```
+ */
+declare class CacheTokenStore implements SSETokenStore {
+    private cache;
+    private prefix;
+    constructor(cache: CacheClient);
+    set(token: string, data: SSEToken): Promise<void>;
+    consume(token: string): Promise<SSEToken | null>;
+    cleanup(): Promise<void>;
+}
+declare class SSETokenManager {
+    private store;
+    private ttl;
+    private cleanupTimer;
+    constructor(config?: SSETokenManagerConfig);
+    /**
+     * How long an issued token stays valid, in milliseconds.
+     *
+     * Exposed so a caller that has to report an expiry to its client computes the same
+     * number this manager stamps on the token, instead of assuming the default.
+     */
+    get ttlMs(): number;
+    /**
+     * Issue a new one-time-use token for the given subject
+     */
+    issue(subject: string): Promise<string>;
+    /**
+     * Verify and consume a token
+     * @returns subject string if valid, null if invalid/expired/already consumed
+     */
+    verify(token: string): Promise<string | null>;
+    /**
+     * Cleanup timer and resources
+     */
+    destroy(): void;
+}
+
+export { CacheTokenStore as C, SSETokenManager as S, type SSEToken as a, type SSETokenManagerConfig as b, type SSETokenStore as c };

package/dist/{types-ClQVomgV.d.ts → types-B4DuGCyM.d.ts}

@@ -62,6 +62,38 @@ interface ContractOperation {
     /** What the client reads. */
     response: JsonSchema;
 }
+/**
+ * One contracted SSE event.
+ *
+ * On the wire the frame's `event:` field is `name`, and its `data` is the JSON
+ * `{ "event": name, "data": payload }` with `payload` matching `payload` here.
+ */
+interface ContractEvent {
+    /**
+     * Router key — what a client subscribes to with `events=` and what the
+     * frame's `event:` field carries. Not `defineEvent`'s first argument, which
+     * never reaches the wire.
+     */
+    name: string;
+    /** Contract version the event first appeared in. */
+    since: string;
+    /** Present only when the event is announced for removal. */
+    deprecatedIn?: string;
+    /** Present only when the event is gone. */
+    removedIn?: string;
+    /** The payload schema. Compared under the response rules: events flow server → client. */
+    payload: JsonSchema;
+}
+/** How a client reaches the contracted events, and which events it may receive. */
+interface ContractEvents {
+    /** The path a client opens the stream on. */
+    streamPath: string;
+    /** The path a client posts to for a one-time stream token when `auth` is `tokenExchange`. */
+    tokenPath: string;
+    auth: 'none' | 'tokenExchange';
+    /** Sorted by name. */
+    items: ContractEvent[];
+}
 /**
  * How a client's version is judged against the server's.
  *
@@ -91,6 +123,11 @@ interface ContractDocument {
     compatibilityPolicy: CompatibilityPolicy;
     /** Sorted by name, so the file does not churn on router reordering. */
     operations: ContractOperation[];
+    /**
+     * Present only when the app's event router contracts at least one event,
+     * so an app without contracted events writes the document it always did.
+     */
+    events?: ContractEvents;
 }
 /** A released snapshot: the document plus the digest that pins it. */
 interface ContractSnapshot {
@@ -100,16 +137,18 @@ interface ContractSnapshot {
     document: ContractDocument;
 }
 /** What a gate violation is about. */
-type ContractViolationKind = 'operation.removed' | 'operation.path-changed' | 'operation.method-changed' | 'request.required-field-added' | 'request.field-became-required' | 'request.type-changed' | 'response.field-removed' | 'response.field-became-optional' | 'response.type-changed' | 'usage.undecidable' | 'usage.still-called' | 'snapshot.digest-mismatch';
+type ContractViolationKind = 'operation.removed' | 'operation.path-changed' | 'operation.method-changed' | 'request.required-field-added' | 'request.field-became-required' | 'request.type-changed' | 'response.field-removed' | 'response.field-became-optional' | 'response.type-changed' | 'event.removed' | 'events.stream-path-changed' | 'events.auth-changed' | 'event.payload.field-removed' | 'event.payload.field-became-optional' | 'event.payload.type-changed' | 'usage.undecidable' | 'usage.still-called' | 'usage.still-subscribed' | 'snapshot.digest-mismatch';
 /** One reason the build refuses. */
 interface ContractViolation {
     kind: ContractViolationKind;
     /** Operation name, when the violation belongs to one. */
     operation?: string;
-    /** Where inside the operation, e.g. `request.body.email`. */
+    /** Event name, when the violation belongs to one. */
+    event?: string;
+    /** Where inside the operation or event, e.g. `request.body.email`, `payload.userId`. */
     location?: string;
     /** What went wrong, in one line. */
     detail: string;
 }
 
-export type { ContractDocument as C, JsonSchema as J, ContractViolation as a, ContractOperation as b, ContractSnapshot as c, CompatibilityPolicy as d, ContractRequest as e, ContractViolationKind as f };
+export type { ContractDocument as C, JsonSchema as J, ContractViolation as a, ContractOperation as b, ContractSnapshot as c, CompatibilityPolicy as d, ContractEvent as e, ContractEvents as f, ContractRequest as g, ContractViolationKind as h };

package/dist/{types-ZQODsBft.d.ts → types-B8zAxFsE.d.ts}

@@ -1,5 +1,6 @@
 import { Context } from 'hono';
-import { b as EventRouterDef, I as InferEventNames, e as InferEventPayload, i as SSETokenStore, S as SSETokenManager } from './token-manager-BT5EnUAR.js';
+import { E as EventRouterDef, I as InferEventNames, g as InferEventPayload } from './router-CysBmgv3.js';
+import { c as SSETokenStore, S as SSETokenManager } from './token-manager-Ckjt2-qq.js';
 
 /**
  * SSE Types

package/dist/{types-2AbaW4Ie.d.ts → types-W4u_S0lF.d.ts}

@@ -1,5 +1,6 @@
 import { Context } from 'hono';
-import { E as EventDef, b as EventRouterDef, I as InferEventNames, e as InferEventPayload, i as SSETokenStore, S as SSETokenManager } from './token-manager-BT5EnUAR.js';
+import { a as EventDef, i as EventRouterBase, I as InferEventNames, g as InferEventPayload } from './router-CysBmgv3.js';
+import { c as SSETokenStore, S as SSETokenManager } from './token-manager-Ckjt2-qq.js';
 
 /**
  * WebSocket Types
@@ -8,9 +9,9 @@ import { E as EventDef, b as EventRouterDef, I as InferEventNames, e as InferEve
 /**
  * WebSocket Router Definition
  *
- * Extends EventRouterDef with client→server message handlers.
+ * Extends the event router shape with client→server message handlers.
  */
-interface WSRouterDef<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers = WSMessageHandlers> extends EventRouterDef<TEvents> {
+interface WSRouterDef<TEvents extends Record<string, EventDef<any>>, TMessages extends WSMessageHandlers = WSMessageHandlers> extends EventRouterBase<TEvents> {
     messages: TMessages;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.18",
+    "version": "0.3.0-beta.19",
     "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

@@ -264,7 +264,8 @@ export type RouteName = keyof RouteMap;
 
 ## Built-in: `@spfn/core:contract`
 
-Writes `contracts/current.json` — every route carrying `.contract()` — and on a **build** compares
+Writes `contracts/current.json` — every route carrying `.contract()`, and with `eventRouterPath`
+every SSE event carrying `.contract()` — and on a **build** compares
 it against the newest released snapshot, refusing changes that would break a client already in the
 field. Full behaviour lives in [`../contract/README.md`](../contract/README.md); this section is the
 generator's own surface.
@@ -276,6 +277,8 @@ generator's own surface.
 | `name` | `'@spfn/core:contract'` | yes | — | Generator identifier (literal). |
 | `routerPath` | `string` | yes | — | Router file, relative to project root. Throws at construction if missing. |
 | `routerExport` | `string` | no | `appRouter` → `default` → `router` | Export holding the `defineRouter()` result. |
+| `eventRouterPath` | `string` | no | — | Event router file, relative to project root. Loaded like the router (same `NODE_ENV` pin, same tsconfig aliases) and watched; its contracted events become the document's `events` section. Unset → no section. |
+| `eventRouterExport` | `string` | no | `eventRouter` → `default` | Export holding the `defineEventRouter()` result. |
 | `outputDir` | `string` | no | `'./contracts'` | Holds `current.json`, `released/`, `usage/`. |
 | `additionalRouteDirs` | `string[]` | no | `[]` | Extra route dirs to watch. |
 
@@ -298,12 +301,18 @@ costs a module import and no infrastructure — `@spfn/auth`'s 43 routes load in
 - The router file is missing, or the module will not load (it names the module and the cause —
   it never skips quietly).
 - No router export is found under the configured or default names.
+- `eventRouterPath` is set and the file is missing, or holds no event router (an object with
+  `events` and `eventNames`) under the configured or default names — the message names the
+  candidates it tried.
+- The event router contracts events without a router-level `.contract()`, or a contracted event
+  has no payload schema, no `since`, or the reserved key `connected` / `ping`.
 - Two contracted routes share a name, or a contracted route has no method, path, `since` or
   `response`.
 - The router the generator was pointed at contains a conditional spread
   (`...(flag ? { route } : {})`), which would make the contract describe whichever way the
   generator happened to run. Same guard as `route-map` — see its bullet for exactly what is
-  scanned and what is allowed.
+  scanned and what is allowed. The event router file gets the same scan for
+  `defineEventRouter({ ...(flag ? { event } : {}) })`.
 - On the `build` trigger only: the contract breaks the newest released snapshot.
 
 `spfn dev` generates but never refuses — being unable to hold a half-finished route mid-edit would

package/src/contract/README.md

@@ -28,6 +28,7 @@ The clients that need a contract are the ones compiled and shipped separately.
 | Path | Contents |
 |------|----------|
 | `@spfn/core/route` | `.contract()` on the route builder, `RouteContract`, `RouteAuthProfile` |
+| `@spfn/core/event` | `.contract()` on `defineEvent` and `defineEventRouter`, `EventContract`, `EventRouterContract` |
 | `@spfn/core/contract` | Everything below: collect, compare, snapshots, usage, the gate |
 | `@spfn/core/codegen` | `@spfn/core:contract` generator, `ContractGeneratorConfig` |
 
@@ -127,6 +128,8 @@ export default defineConfig({
 |--------|---------|---------|
 | `routerPath` | — | Router file, relative to the project root. Required. |
 | `routerExport` | `appRouter`, then `default`, then `router` | Export holding the `defineRouter()` result. |
+| `eventRouterPath` | — | Event router file, relative to the project root. Set it to publish contracted SSE events — see [Events](#events). |
+| `eventRouterExport` | `eventRouter`, then `default` | Export holding the `defineEventRouter()` result. |
 | `outputDir` | `./contracts` | Directory holding `current.json`, `released/` and `usage/`. |
 | `additionalRouteDirs` | `[]` | Extra directories to watch, for routes outside `src/server/routes`. |
 
@@ -182,6 +185,98 @@ path. That is what lets a moved path be reported as a broken promise instead of
 operation vanishing and another appearing. Names must therefore be unique across the whole router
 tree; two contracted routes sharing a name is refused at generation time.
 
+### Events
+
+A native app subscribes to SSE events by name and decodes each payload itself. Without the events
+in the contract both are hand-written, and both break at runtime — the stream answers 400 with
+`validEvents`, or a decoder throws — instead of at build. Contracted events close that gap.
+
+| Change | Previous snapshot exists | No snapshot yet |
+|--------|--------------------------|-----------------|
+| event added | pass | pass |
+| event removed | **usage check**, against the usage file's `events` | pass |
+| stream path changed | refuse (`events.stream-path-changed`) | pass |
+| auth mode changed | refuse (`events.auth-changed`) | pass |
+| payload field added | pass | pass |
+| payload field removed | refuse (`event.payload.field-removed`) | pass |
+| payload required → optional | refuse (`event.payload.field-became-optional`) | pass |
+| payload optional → required | pass | pass |
+| payload type or constraint changed | refuse (`event.payload.type-changed`) | pass |
+| baseline has no `events` section | pass — nothing was promised | pass |
+| current has no `events` section | every baseline event is **removed** | pass |
+
+A payload flows server → client, so it is judged under the **response** rules — the same walk,
+with the violation kinds renamed.
+
+**Declaring.** Opt in per event, and once on the router:
+
+```ts
+// src/server/events.ts
+import { defineEvent, defineEventRouter } from '@spfn/core/event';
+
+const sessionActivity = defineEvent('session.activity', Type.Object({ sessionId: Type.String() }))
+    .contract({ since: '1.0.0' });             // deprecatedIn?, removedIn? as on routes
+
+export const eventRouter = defineEventRouter({ sessionActivity })
+    .contract({ auth: 'tokenExchange' });      // streamPath?: string, default '/events/stream'
+```
+
+and point the generator at the file with `eventRouterPath: './src/server/events.ts'`. An event
+without `.contract()` is untouched and never appears. A router with no contracted event produces no
+`events` section at all, so an app that contracts none writes exactly the document it wrote before.
+
+`.contract()` on an event may be called once — an event is defined once and shared, so a second call
+throws instead of one declaration silently winning. A router `streamPath` that does not start with
+`/` throws where it is declared.
+
+**Refused at collection**, each with a message saying what to do:
+
+- contracted events on a router with no `.contract()` of its own — the contract cannot say whether
+  a client must exchange a token first;
+- a contracted event without a payload schema (`defineEvent(name)`) — its frame carries no `data`;
+  declare `Type.Object({})` and emit `{}` instead;
+- a contracted event under the key `connected` or `ping` — those are the stream's own frames;
+- a contracted event with no `since`.
+
+**What a reader of the document needs.**
+
+```json
+"events": {
+    "streamPath": "/events/stream",
+    "tokenPath": "/events/token",
+    "auth": "tokenExchange",
+    "items": [{ "name": "sessionActivity", "since": "1.0.0", "payload": { "type": "object", "…": "…" } }]
+}
+```
+
+- `name` is the **router key** — what a client lists in `?events=` and what the frame's `event:`
+  field carries. `defineEvent`'s first argument never reaches the wire and is not published. The same
+  `EventDef` registered under two keys is two items.
+- A frame's `data` is the JSON `{ "event": name, "data": payload }`, with `payload` matching the
+  item's schema.
+- `connected` (once, when the stream opens) and `ping` (keep-alive) frames are the stream's own and
+  are not items.
+- With `auth: "tokenExchange"` the client first posts to `tokenPath`, then opens
+  `streamPath?events=…&token=…`. `tokenPath` is derived from `streamPath` exactly as the server
+  derives it.
+- An `authorize` hook may narrow which contracted events a given connection receives. That is
+  per-connection policy, not a promise the contract makes, and the document does not describe it.
+
+**The boot check.** The generator reads the event router only, never the server config. So
+`createServer` checks the router's contract against `.events()` before anything is served: the
+contract's `streamPath` (default `/events/stream`) must equal the path `.events()` registers, and
+`auth: 'tokenExchange'` must match `.events({ auth: { enabled: true } })`. A mismatch refuses to
+boot:
+
+```
+SSE event router contract declares streamPath /sse but .events() registers /events/stream; the contract would describe a path the server does not serve
+```
+
+A router without `.contract()` is not checked.
+
+**Conditional registration is refused here too.** `defineEventRouter({ ...(flag ? { x } : {}) })`
+in the event router file stops the generator, for the same reason as a conditional route.
+
 ### Request — safe when the server grows more tolerant
 
 | Change | Result | Why |
@@ -225,9 +320,15 @@ A removal is decided against `contracts/usage/<platform>-<appVersion>.json`, whi
 client writes:
 
 ```json
-{ "platform": "ios", "appVersion": "2.4.1", "operations": ["getUser", "listItems"] }
+{ "platform": "ios", "appVersion": "2.4.1", "operations": ["getUser", "listItems"], "events": ["sessionActivity"] }
 ```
 
+`events` lists the contracted events the client subscribes to. A file without the key subscribes
+to none — an app released before events were contracted cannot be subscribed to one — and a value
+that is not an array of names is refused like a bad `operations`. A removed event is judged by the
+table below exactly as a removed operation, and a client still listing it is reported as
+`usage.still-subscribed` with its platform and version.
+
 | Situation | Verdict |
 |-----------|---------|
 | usage directory missing, or holds no file | **refuse** — undecidable, which is not a pass |
@@ -250,7 +351,9 @@ Named here rather than left to be discovered:
   approved case table; adding it is a deliberate decision, not a quiet extension.
 - **Runtime response validation.** Whether a handler actually returns what it declared is a separate
   feature from generating a contract, and integration tests already cover it for contracted routes.
-- **WebSocket and SSE.** The contract covers REST operations only.
+- **WebSocket.** The contract covers REST operations and SSE events; a WebSocket router is not
+  contracted.
+- **`since` and `deprecatedIn` changes on an event**, and per-connection narrowing by `authorize`.
 - **How a client produces its usage file.** That belongs to the client's toolchain.
 - **Multipart routes are refused, not checked.** See below.
 
@@ -307,16 +410,21 @@ route.get('/x').contract({ since, response, auth?, requiresSession?, deprecatedI
 defineRouter({...}).contractVersion('1.2.0')    // the version's source
 type RouteContract, RouteAuthProfile
 
+// @spfn/core/event
+defineEvent(name, schema).contract({ since, deprecatedIn?, removedIn? })
+defineEventRouter({...}).contract({ auth, streamPath? })
+type EventContract, EventRouterContract
+
 // @spfn/core/contract
-collectContractDocument(router)                 // Router → ContractDocument
-compareDocuments(before, after)                 // → { violations, removedOperations }
+collectContractDocument(router, eventRouter?)   // Router (+ event router) → ContractDocument
+compareDocuments(before, after)                 // → { violations, removedOperations, removedEvents }
 compareOperation(before, after)                 // → ContractViolation[]
 checkContract(contractsDir, current)            // the gate → { baselineVersion, violations, warnings }
 formatViolations(violations)                    // → the message a failing build prints
 
 readCurrentDocument(dir) / writeCurrentDocument(dir, document)
 listSnapshots(dir) / newestSnapshot(dir) / readSnapshot(file) / writeSnapshot(dir, document)
-readUsageRecords(usageDir) / callersOf(operation, records)
+readUsageRecords(usageDir) / callersOf(operation, records) / subscribersOf(event, records)
 compareVersions(a, b)
 canonicalize / stableStringify / stableStringifyPretty / stableDigest
 

package/src/event/README.md

@@ -42,7 +42,11 @@ From `@spfn/core/event`:
 - `defineEventRouter(events)` — group events for SSE
 - `defineWSRouter({ events, messages? })` — group events + message handlers for WebSocket
 - `eventRouteMap` — `{ eventsToken: { method: 'POST', path: '/events/token' } }` (merge into RPC proxy)
+- `.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))
 - Types: `EventDef`, `EventHandler`, `InferEventPayload`, `PubSubCache`, `JobQueueSender`,
+  `EventContract`, `EventRouterContract`,
   `EventRouterDef`, `InferEventNames`, `InferEventPayloads`,
   `InferRouterEventPayload` (the two-arg router variant — see note)
 
@@ -128,6 +132,7 @@ Promise<void>` otherwise. Handlers run via `Promise.allSettled` — see
 | `unsubscribeAll()` | `() => void` | drop all in-memory handlers |
 | `emit(payload?)` | `Promise<void>` | fan-out to handlers (or cache) + job queues |
 | `useCache(cache)` | `(PubSubCache) => Promise<EventDef>` | enable cross-instance broadcast (must `await`) |
+| `contract(contract)` | `(EventContract) => EventDef` | publish in the contract; returns the same event; a second call throws |
 
 > `_registerJobQueue` and `_payload` exist on the interface but are **internal** —
 > `_registerJobQueue` is called by `@spfn/core/job` when a job does `.on(event)`; `_payload`
@@ -204,6 +209,42 @@ SSEAuthConfig<TRouter> }`. The `auth` field is the **generic** `SSEAuthConfig<TR
 > `pingInterval`, `auth`, and `maxQueue`. Setting custom `headers` here is a no-op — set
 > response headers in middleware instead.
 
+### Contracted events (for separately compiled clients)
+
+A web client takes its event names and payload types from `typeof eventRouter`. A native app
+cannot, so it hand-writes both — and they break at runtime. Declaring `.contract()` puts the
+events into `contracts/current.json`, where the contract gate refuses a breaking change at build:
+
+```typescript
+export const sessionActivity = defineEvent('session.activity', Type.Object({
+    sessionId: Type.String(),
+})).contract({ since: '1.0.0' });            // deprecatedIn?, removedIn? as on routes
+
+export const eventRouter = defineEventRouter({ sessionActivity, userCreated })
+    .contract({ auth: 'tokenExchange' });     // streamPath?: string, default '/events/stream'
+```
+
+- Only events carrying `.contract()` are published (`userCreated` above is not). The published
+  name is the **router key** (`sessionActivity`), the name on the wire — not `'session.activity'`.
+- `.contract()` on an event returns the same event and may be called once; a second call throws.
+- The router's `auth` is required: `'tokenExchange'` when `.events()` enables `auth`, else
+  `'none'`. A `streamPath` not starting with `/` throws where it is declared.
+- Point the contract generator at the file with `eventRouterPath` — see
+  [the contract README](../contract/README.md#events).
+
+**Boot check.** When the event router declares `.contract()`, `createServer` compares it with
+`.events()` before anything is served and refuses to start on a mismatch: the contract's
+`streamPath` (default `/events/stream`) must equal `.events({ path })` (same default), and
+`auth: 'tokenExchange'` must match `auth.enabled: true`. A router without `.contract()` is not
+checked.
+
+```
+SSE event router contract declares streamPath /sse but .events() registers /events/stream; the contract would describe a path the server does not serve
+```
+
+An `authorize` hook narrowing which events a connection receives is per-connection policy and
+not part of the contract.
+
 ---
 
 ## SSE authentication (Token Exchange)
@@ -699,8 +740,12 @@ interface EventDef<TPayload = void> {
     unsubscribeAll: () => void;
     emit: TPayload extends void ? () => Promise<void> : (payload: TPayload) => Promise<void>;
     useCache: (cache: PubSubCache) => Promise<EventDef<TPayload>>;
+    readonly _contract?: EventContract;
+    contract: (contract: EventContract) => EventDef<TPayload>;
 }
 
+interface EventContract { since: string; deprecatedIn?: string; removedIn?: string; }
+
 type EventHandler<TPayload> = (payload: TPayload) => void | Promise<void>;
 type InferEventPayload<TEvent> = TEvent extends EventDef<infer P> ? P : never; // single-arg
 
@@ -714,7 +759,10 @@ interface EventRouterDef<TEvents> {
     readonly events: TEvents;
     readonly eventNames: (keyof TEvents)[];
     readonly _types: { [K in keyof TEvents]: TEvents[K]['_payload'] };
+    readonly _contract?: EventRouterContract;
+    contract: (contract: EventRouterContract) => EventRouterDef<TEvents>;
 }
+interface EventRouterContract { auth: 'none' | 'tokenExchange'; streamPath?: string; }
 type InferEventNames<T>     = /* keyof router events as string union */;
 type InferEventPayloads<T>  = T['_types'];
 // router two-arg payload, exported as `InferRouterEventPayload`: