@voltro/protocol 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -54,6 +54,9 @@ export declare const anonymousSubject: (tenantId: string | null) => Subject;
 /** A guard entry is either a scope check or a relationship check. */
 export declare type AnyCheckSpec = GuardCheckSpec | PolicyCheckSpec;
 
+/** Any declared event, with the generics erased — for registries and audits. */
+export declare type AnyEventDescriptor = EventDescriptor<string, Schema.Schema.Any, Schema.Schema.Any>;
+
 /** A guard is either a scope check or a relationship check. */
 export declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input>;
 
@@ -693,6 +696,94 @@ export declare const defineAction: <const Name extends string, Input extends Sch
     readonly internal?: boolean;
 }) => ActionProcedureDescriptor<Name, Input, Output, Error>;
 
+/**
+ * Declare an event.
+ *
+ * ```ts
+ * export const gameStarted = defineEvent({
+ *   name: 'games.started',
+ *   key: Schema.Struct({ arenaId: Schema.String }),
+ *   payload: Schema.Struct({ gameId: Schema.String, startedAt: Schema.Number }),
+ *   guards: [{ scope: 'display:read' }],
+ * })
+ * ```
+ */
+export declare const defineEvent: <const Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(options: {
+    /**
+     * Wire identifier, `camelCase.dotted` like an rpc tag — and it shares the rpc
+     * tag COLLISION SPACE, so a duplicate aborts boot rather than resolving itself
+     * at the first delivery. Two declarations answering to one name is precisely
+     * the failure mode a string channel has; a name that can collide silently
+     * would reintroduce it one level up.
+     */
+    readonly name: Name;
+    /**
+     * WHERE it goes. Part of the contract, not a filter the client applies:
+     * a subscriber receives only events published under a key it asked for, so
+     * the server never sends the others at all.
+     *
+     * ONLY ROUTING FIELDS BELONG HERE. Every field fragments the subscriber set
+     * and costs fan-out dedup — a discriminator the handler reads (`gameType`) is
+     * payload, an address the delivery is decided by (`arenaId`) is key.
+     *
+     * The tenant is NOT part of it and must never be added: it is derived from the
+     * subject on both sides, so a cross-tenant delivery is impossible by
+     * construction rather than by remembering to filter.
+     */
+    readonly key: Key;
+    /** WHAT happened. Decoded when publishing, so a mismatch is a typed error at
+     *  the PRODUCER instead of a broken handler at every consumer. */
+    readonly payload: Payload;
+    /**
+     * WHO MAY LISTEN — the same vocabulary as a query's guards, so a
+     * resource-scoped rule ("may this terminal watch this arena") stays
+     * declarative. `ScopeError` is merged into the wire error union automatically.
+     *
+     * Re-checked when the SUBJECT changes (a revoked role ends the stream), not on
+     * every delivery. Per-delivery authorization is the design a comparable
+     * product measured into a scaling wall: one check per subscriber per message
+     * makes throughput scale with the audience instead of the publish rate.
+     */
+    readonly guards?: Guards<Schema.Schema.Type<Key>>;
+    /**
+     * Deliver recently-buffered events on a FIRST attach. Default `false`, and the
+     * default is the interesting half.
+     *
+     * A fresh subscriber wanting only what happens from now on, and a RECONNECTING
+     * subscriber wanting the messages it missed, are different requests that read
+     * as one contradiction ("never replay history" vs "never lose a message"). They
+     * are separated here: a first attach starts empty unless it opts in, while a
+     * re-attach always resumes from the last serial the client saw. Mounting a
+     * component is not the same event as a WebSocket dropping, and the framework
+     * knows which one it is.
+     */
+    readonly rewind?: boolean;
+    /**
+     * Deliver this event to subscribed HTTP targets as well.
+     *
+     * The unification the whole design is for: ONE declaration, and the audiences
+     * are consumers of it. Without this an app that both fans an event out to its
+     * screens and posts it to a partner declares the thing twice, in two shapes,
+     * and the two drift — which is the defect a declaration exists to remove, one
+     * level up from the string channel it already removed.
+     *
+     * Requires `@voltro/plugin-webhooks`. Absent ⇒ no outbound delivery, and no
+     * cost.
+     */
+    readonly webhook?: EventWebhookSpec;
+    /**
+     * `'each'` (default) — every delivery matters; a slow subscriber loses the
+     * oldest and is told how many.
+     *
+     * `'latest'` — a newer delivery supersedes a pending one; a slow subscriber
+     * gets the current value and is told nothing, because nothing was lost.
+     *
+     * See {@link EventDeliverySemantics}. The test is "would a consumer be wrong
+     * to miss one?" — not "is this event frequent?".
+     */
+    readonly delivery?: EventDeliverySemantics;
+}) => EventDescriptor<Name, Key, Payload>;
+
 export declare const defineMutation: <const Name extends string, Input extends Schema.Schema.Any, Output extends Schema.Schema.Any, Error extends Schema.Schema.All = typeof Schema.Never>(options: {
     readonly name: Name;
     readonly input: Input;
@@ -878,6 +969,17 @@ export declare const diffRows: (prev: ReadonlyArray<PatchRow>, next: ReadonlyArr
  */
 export declare const effectiveScopes: (subject: Subject) => ReadonlyArray<string>;
 
+/**
+ * Canonical string for a routing key.
+ *
+ * Object key ORDER must not change the routing: `{a,b}` and `{b,a}` are the same
+ * address, and a subscriber that spelled its literal in the other order is the
+ * kind of never-matches bug this whole design exists to make impossible. Sorting
+ * the entries is what makes the two sides agree without either knowing about the
+ * other.
+ */
+export declare const encodeEventKey: (key: unknown) => string;
+
 /**
  * Read the `_tag` off a thrown error value, or `undefined` when it has none.
  *
@@ -895,6 +997,290 @@ export declare const effectiveScopes: (subject: Subject) => ReadonlyArray<string
  */
 export declare const errorTag: (err: unknown) => string | undefined;
 
+/**
+ * The full routing address: tenant, event, key.
+ *
+ * The tenant is FIRST and is supplied by the caller of this function from the
+ * SUBJECT — never from anything a client sent. Two apps in two tenants
+ * publishing `games.started` for `arena-1` are addressing different channels,
+ * and no amount of key collision can make them the same one.
+ *
+ * Separated by `EVENT_ROUTE_SEP` — NUL, and NOBODY WRITES IT INLINE. The character is
+ * the right separator (it cannot occur in a tenant id or an event name, so no
+ * pair of parts can spell another pair's address), but a source file containing
+ * a literal one is BINARY to every text tool: `grep` skips it and prints
+ * nothing, which reads exactly like a clean file. This repo has already lost an
+ * audit that way.
+ *
+ * The constant exists because escaping it correctly at each site does NOT work
+ * in practice: writing this module produced three literals in three different
+ * files — including inside the comment warning against them — before the
+ * separator was hoisted. So there is exactly one place the character appears,
+ * and `parseEventRoute` / `formatEventRoute` mean no consumer needs to name it
+ * at all. `eventRouteHygiene` in the test file scans the whole package.
+ */
+export declare const EVENT_ROUTE_SEP = "\0";
+
+/** First element of every subscription: the stream is live from here on. */
+export declare const eventAttached: Schema.Struct<{
+    _tag: Schema.Literal<["attached"]>;
+}>;
+
+/**
+ * What it means for a subscriber to fall behind.
+ *
+ * `'each'` — every delivery matters. A subscriber that cannot keep up loses the
+ * OLDEST and is told exactly how many. This is the default because it is the
+ * safe reading: an arena that misses a game-start signal must find out.
+ *
+ * `'latest'` — only the current value matters, and a newer delivery SUPERSEDES a
+ * pending one. A subscriber that falls behind receives the current state on its
+ * next read and is told nothing, because nothing was lost: for a 60Hz stream of
+ * positions, frame 1 stopped being interesting the moment frame 2 existed.
+ *
+ * The distinction is semantic, not a performance knob. Choosing `'latest'` for a
+ * stream where each delivery matters silently 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 a loss.
+ *
+ * The honest test: **would a consumer be wrong to miss one?** If the next value
+ * supersedes it, that is `'latest'` — and it is probably state rather than an
+ * event at all.
+ */
+export declare type EventDeliverySemantics = 'each' | 'latest';
+
+/**
+ * A declared event: a name, a routing key, a payload, and who may listen.
+ *
+ * Type parameters are inferred from the Schemas, and every call site — `publish`,
+ * `useEvent`, a workflow trigger — derives its types from this one value.
+ */
+export declare interface EventDescriptor<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any> {
+    readonly kind: 'event';
+    readonly name: Name;
+    readonly key: Key;
+    readonly payload: Payload;
+    /** Who may LISTEN. Re-checked when the subject changes, not per delivery —
+     *  see `EventDefinition.guards` for why that distinction is deliberate. */
+    readonly guards: Guards<Schema.Schema.Type<Key>> | undefined;
+    /** Deliver buffered events on a FIRST attach. Default false. */
+    readonly rewind: boolean | undefined;
+    /** `'each'` (default) or `'latest'` — see the definer. */
+    readonly delivery: EventDeliverySemantics | undefined;
+    /** Opt this event into outbound HTTP delivery. See `EventWebhookSpec`. */
+    readonly webhook: EventWebhookSpec | undefined;
+}
+
+/**
+ * One delivery.
+ *
+ * `origin` + `n` are what make a lost message COUNTABLE. `n` is monotonic per
+ * (origin, event, tenant, key), so a subscriber that sees 7 then 9 knows exactly
+ * one delivery is gone — where a dropping buffer, which is what every
+ * `onSlowConsumer: 'drop-oldest'` option in this space actually is, discards in
+ * silence by definition. Silence is the one outcome you cannot build on: an
+ * arena cannot tell "no game started" from "the start signal was dropped".
+ *
+ * It is per ORIGIN rather than global because two instances publishing the same
+ * key have no shared clock and no shared counter. A global sequence would need
+ * one owner per key — an extra hop on every publish and a failover story for
+ * every key — which is a real architecture (a single-threaded actor per room)
+ * and not the one this framework has.
+ */
+export declare const eventEnvelope: <P extends Schema.Schema.Any>(payload: P) => Schema.Struct<{
+    _tag: Schema.Literal<["event"]>;
+    /** Publishing instance id — serials are only comparable within one. */
+    origin: typeof Schema.String;
+    /** Monotonic per (origin, event, tenant, key). */
+    n: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    payload: P;
+}>;
+
+/** Told to the subscriber when the SERVER knows it cannot fill a gap. */
+export declare const eventGap: Schema.Struct<{
+    _tag: Schema.Literal<["gap"]>;
+    /** How many deliveries are known lost. Never a guess: a shortfall is computed
+     *  from the requested serial against what the ring still holds. */
+    missed: typeof Schema.Number;
+    /** `buffer` — evicted before this subscriber could be served.
+     *  `resume` — the re-attach asked for a serial older than the ring. */
+    reason: Schema.Literal<["buffer", "resume"]>;
+}>;
+
+/** The routing key did not decode against the descriptor's schema. */
+export declare class EventKeyInvalid extends EventKeyInvalid_base {
+}
+
+declare const EventKeyInvalid_base: Schema.TaggedErrorClass<EventKeyInvalid, "EventKeyInvalid", {
+    readonly _tag: Schema.tag<"EventKeyInvalid">;
+} & {
+    event: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** The payload did not decode against the descriptor's schema. */
+export declare class EventPayloadInvalid extends EventPayloadInvalid_base {
+}
+
+declare const EventPayloadInvalid_base: Schema.TaggedErrorClass<EventPayloadInvalid, "EventPayloadInvalid", {
+    readonly _tag: Schema.tag<"EventPayloadInvalid">;
+} & {
+    event: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/** The encoded envelope exceeds `MAX_EVENT_ENVELOPE_BYTES`. */
+export declare class EventPayloadTooLarge extends EventPayloadTooLarge_base {
+}
+
+declare const EventPayloadTooLarge_base: Schema.TaggedErrorClass<EventPayloadTooLarge, "EventPayloadTooLarge", {
+    readonly _tag: Schema.tag<"EventPayloadTooLarge">;
+} & {
+    event: typeof Schema.String;
+    bytes: typeof Schema.Number;
+    limit: typeof Schema.Number;
+}>;
+
+export declare type EventResumePoint = {
+    readonly origin: string;
+    readonly n: number;
+};
+
+/** Where a re-attaching subscriber left off, per origin. */
+export declare const eventResumePoint: Schema.Struct<{
+    origin: typeof Schema.String;
+    n: typeof Schema.Number;
+}>;
+
+export declare const eventRoute: (tenantId: string | null, event: string, key: unknown) => string;
+
+export declare type EventStreamEvent<P> = {
+    readonly _tag: 'attached';
+} | {
+    readonly _tag: 'event';
+    readonly origin: string;
+    readonly n: number;
+    readonly emittedAt: number;
+    readonly payload: P;
+} | {
+    readonly _tag: 'gap';
+    readonly missed: number;
+    readonly reason: 'buffer' | 'resume';
+};
+
+/**
+ * What a subscription emits. `attached` first, then `event`s, with `gap`
+ * interleaved whenever the server can prove a loss.
+ */
+export declare const eventStreamEvent: <P extends Schema.Schema.Any>(payload: P) => Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["attached"]>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["event"]>;
+    /** Publishing instance id — serials are only comparable within one. */
+    origin: typeof Schema.String;
+    /** Monotonic per (origin, event, tenant, key). */
+    n: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    payload: P;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["gap"]>;
+    /** How many deliveries are known lost. Never a guess: a shortfall is computed
+     *  from the requested serial against what the ring still holds. */
+    missed: typeof Schema.Number;
+    /** `buffer` — evicted before this subscriber could be served.
+     *  `resume` — the re-attach asked for a serial older than the ring. */
+    reason: Schema.Literal<["buffer", "resume"]>;
+}>]>;
+
+/**
+ * The subscription payload: the key, plus where to resume.
+ *
+ * `resume` present ⇒ this is a RE-attach and the client is owed continuity;
+ * absent ⇒ a first attach, which gets nothing older than itself unless the
+ * descriptor opted into `rewind`. The distinction lives on the wire because only
+ * the client knows whether it has seen this stream before — the server cannot
+ * tell a reconnect from a fresh mount.
+ */
+export declare const eventSubscribeInput: <K extends Schema.Schema.Any>(key: K) => Schema.Struct<{
+    key: K;
+    resume: Schema.optional<Schema.Array$<Schema.Struct<{
+        origin: typeof Schema.String;
+        n: typeof Schema.Number;
+    }>>>;
+}>;
+
+/**
+ * Lift an event descriptor into its rpc.
+ *
+ * A `stream: true` rpc, like a query — the framework's push transport is the
+ * WebSocket a subscription already holds open, and reusing it is why `useEvent`
+ * shares one connection lifecycle, one reconnect policy and one devtools view
+ * with `useSubscription` instead of being a second realtime concept in the same
+ * app.
+ */
+export declare const eventToRpc: <Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor<Name, Key, Payload>, extraErrors?: ReadonlyArray<Schema.Schema.All>) => Rpc.Rpc<Name, Schema.Struct<{
+    key: Key;
+    resume: Schema.optional<Schema.Array$<Schema.Struct<{
+        origin: typeof Schema.String;
+        n: typeof Schema.Number;
+    }>>>;
+}>, Stream<Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["attached"]>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["event"]>;
+    /** Publishing instance id — serials are only comparable within one. */
+    origin: typeof Schema.String;
+    /** Monotonic per (origin, event, tenant, key). */
+    n: typeof Schema.Number;
+    emittedAt: typeof Schema.Number;
+    payload: Payload;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["gap"]>;
+    /** How many deliveries are known lost. Never a guess: a shortfall is computed
+     *  from the requested serial against what the ring still holds. */
+    missed: typeof Schema.Number;
+    /** `buffer` — evicted before this subscriber could be served.
+     *  `resume` — the re-attach asked for a serial older than the ring. */
+    reason: Schema.Literal<["buffer", "resume"]>;
+}>]>, Schema.Schema.Any | Schema.Schema<never, never, unknown>>, typeof Schema.Never, never>;
+
+/**
+ * The WEBHOOK audience of a declared event.
+ *
+ * Present ⇒ `@voltro/plugin-webhooks` treats this event as an outbound one:
+ * subscribers can register HTTP targets for it and every publish is delivered to
+ * them, signed and retried, from the SAME call that fans it out to clients.
+ *
+ * Structurally typed rather than importing the plugin's own types, and that is a
+ * dependency direction rather than a preference: `@voltro/protocol` is
+ * browser-safe and must not reach a plugin. The plugin reads this block and maps
+ * it onto its own knobs — the shapes are the plugin's to define, so a value here
+ * is a plain number or string, never one of its enums.
+ *
+ * Namespaced under `webhook:` rather than spread across the descriptor because
+ * these settings are meaningless to the other three audiences. A `retry` at the
+ * top level would read as if it applied to client delivery, which is
+ * at-most-once by design and has no retry at all.
+ */
+export declare interface EventWebhookSpec {
+    /** Human-readable summary for the dashboard's event list. */
+    readonly description?: string;
+    /** Payload schema version. Bump when subscribers must adapt. Default 1. */
+    readonly version?: number;
+    /** Default retry policy for new subscriptions (`{ attempts, backoffMs }`). */
+    readonly retry?: {
+        readonly attempts?: number;
+        readonly backoffMs?: number;
+    };
+    /** Shared ceiling across ALL deliveries of this event — the runaway-emit
+     *  guard. Over-limit deliveries are deferred, never dropped. */
+    readonly rateLimit?: {
+        readonly perMinute: number;
+    };
+}
+
 /** Normalize the `exposeAsTool` shorthand. `true` is only valid when the
  *  descriptor carries a top-level `description`; callers pass that in. */
 export declare type ExposeAsTool = boolean | ExposeAsToolSpec;
@@ -952,6 +1338,9 @@ export declare const findAdvisoryResourceGuards: (procedures: ReadonlyArray<{
 /** Record a completed response for replay. */
 export declare const finishIdempotent: (store: IdempotencyStore, scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
 
+/** A route rendered for humans — logs, the inspect surface, the dashboard. */
+export declare const formatEventRoute: (route: string) => string;
+
 /** The currently-registered policy-guard resolver, or `undefined`. */
 export declare const getPolicyGuardResolver: () => PolicyGuardResolver | undefined;
 
@@ -1133,6 +1522,8 @@ export declare interface InsertTarget<Input = unknown, Row = unknown, Item = Rec
     readonly shapeItem?: ((input: Input, optimisticId: string) => Item) | undefined;
 }
 
+export declare const isEventDescriptor: (value: unknown) => value is AnyEventDescriptor;
+
 /** True when every row in the set carries an `id`. The dispatcher uses
  *  this to decide patch-vs-full-snapshot: a result whose rows aren't
  *  id-keyed (rare — a custom projection that drops the id) can't be
@@ -1165,6 +1556,23 @@ export declare const isWireReachable: (descriptor: {
     readonly internal?: boolean | undefined;
 }) => boolean;
 
+/**
+ * How large one encoded envelope may be, on EVERY dialect.
+ *
+ * Postgres `NOTIFY` dies past 8000 bytes and the other transports have no such
+ * bound. Enforcing the limit only where the wire imposes it would make "switch
+ * the broadcast provider" a silent behaviour change — an app developed against
+ * Redis would start failing when it moved to the pg-native path, at the worst
+ * possible moment. So the smallest transport's ceiling is the framework's
+ * ceiling, minus room for the envelope around the payload.
+ *
+ * An oversized payload is also a design smell in its own right: an event says
+ * that something happened, so `photo.added` carries a photo REFERENCE, and the
+ * consumer fetches the photo through a route that can stream, cache and
+ * authorize it.
+ */
+export declare const MAX_EVENT_ENVELOPE_BYTES = 7500;
+
 /** In-memory store — the default for single-process dev + the test double. */
 export declare const memoryIdempotencyStore: () => IdempotencyStore;
 
@@ -1235,6 +1643,13 @@ export declare interface ObservabilityContribution {
     readonly sampler?: unknown;
 }
 
+/** Split a route back into its three parts. */
+export declare const parseEventRoute: (route: string) => {
+    readonly tenantId: string | null;
+    readonly event: string;
+    readonly key: string;
+};
+
 /** A single row in a subscription result. Must carry an `id`; everything
  *  else is opaque to the patch layer. */
 export declare type PatchRow = Readonly<Record<string, unknown>> & {
@@ -1270,6 +1685,41 @@ export declare type PluginActivateHook = (ctx: PluginLifecycleContext) => Effect
  * touches them.
  */
 export declare interface PluginBindContext {
+    /**
+     * This process's replica identity — the same value the event bus stamps as
+     * its publish `origin` and the membership registry announces under.
+     *
+     * ONE id across all three on purpose: a plugin holding state per replica
+     * (presence is the case) must be able to correlate "who owns this" with "is
+     * that one still alive", and three identities for one process would make the
+     * correlation quietly wrong rather than obviously broken.
+     */
+    readonly instanceId?: string;
+    /**
+     * Live instance membership — subscribe to learn when a replica joins, leaves
+     * or restarts.
+     *
+     * Present only when the host provides one. A plugin holding per-replica state
+     * needs it and cannot derive it: pub/sub delivers messages, it does not report
+     * who is on the channel, and an instance that dies simply goes quiet.
+     */
+    readonly membership?: {
+        readonly onChange: (listener: (event: {
+            readonly kind: 'joined' | 'left' | 'restarted';
+            readonly instanceId: string;
+        }) => void) => () => void;
+    };
+    /**
+     * The app's cross-replica broadcast transport, when one is configured.
+     *
+     * Absent ⇒ single instance, which is a complete answer rather than a
+     * degraded one. A plugin must not branch on "do we have a cluster" — that
+     * branch is how a feature comes to work in dev and differ in production.
+     */
+    readonly broadcast?: {
+        readonly publish: (channel: string, payload: string) => unknown;
+        readonly subscribe: (channel: string, handler: (payload: string) => void) => unknown;
+    };
     /**
      * The framework's already-open `SqlClient` (from `@effect/sql`) — the
      * SAME pool the app's store uses. A plugin runs raw SQL through this