@voltro/protocol 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -38,6 +38,28 @@ export declare interface ActionProcedureDescriptor<Name extends string, Input ex
     readonly exposeAsTool: ExposeAsTool | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -54,6 +76,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>;
 
@@ -485,6 +510,28 @@ export declare interface ConnectionInfoValue {
      *  (every `useMutation` call does). Read by `bindMutation` to dedupe a retried
      *  mutation. Absent for callers that don't send it. */
     readonly idempotencyKey?: string;
+    /**
+     * Unix-SECONDS expiry of the credential that authorized this call, when it
+     * has one. Absent for credentials with no expiry (anonymous, a non-expiring
+     * strategy) — and absent means "no bound", so the failure direction is the
+     * behaviour that already existed.
+     *
+     * It exists for LONG-LIVED work. A request is checked once and is over in
+     * milliseconds, so expiry never mattered; an event subscription is a
+     * standing state that reconnects forever by design, so one opened a minute
+     * before the token dies would otherwise keep delivering for days on a
+     * credential that is long gone. `bindEvent` ends the stream here, and
+     * `useEvent`'s existing reconnect immediately re-opens it — which is a NEW
+     * request, so it re-resolves the subject and re-runs the guards for real.
+     * That is what makes the bound seamless rather than a disconnection the app
+     * has to handle: still entitled, it continues; no longer entitled, it fails
+     * loudly instead of quietly continuing.
+     *
+     * This bounds EXPIRY, not revocation. A role revoked mid-session is not
+     * observed until the credential runs out — do not let this field grow a
+     * doc comment that claims otherwise.
+     */
+    readonly credentialExpiresAt?: number;
 }
 
 /** The two credential shapes a connection can hold. `oauth2` = an
@@ -691,8 +738,99 @@ export declare const defineAction: <const Name extends string, Input extends Sch
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: 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;
@@ -734,6 +872,9 @@ export declare const defineMutation: <const Name extends string, Input extends S
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
 }) => MutationProcedureDescriptor<Name, Input, Output, Error>;
 
 /**
@@ -828,6 +969,9 @@ export declare const defineQuery: <const Name extends string, Input extends Sche
      * need to check who is asking.
      */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
 }) => QueryProcedureDescriptor<Name, Input, Output, Error>;
 
 /**
@@ -844,6 +988,22 @@ export declare const defineStream: <const Name extends string, Input extends Sch
      *  dev or serve. Same contract as `internal` on the other definers; a stream
      *  without it would be a hole in the same boundary. */
     readonly internal?: boolean;
+    /** Replace a PLUGIN route answering to this same tag. Explicit, never
+     *  inferred — see `overridesPlugin` on the descriptor. */
+    readonly overridesPlugin?: boolean;
+    /**
+     * WHO MAY LISTEN.
+     *
+     * A stream is the same long-lived grant a subscription is, and it was the one
+     * primitive that could not express authorization at all — queries, mutations
+     * and actions carry `guards:`, streams did not, so any protection lived
+     * hand-written inside an executor where nothing could verify it existed.
+     *
+     * Checked at subscribe and re-checked before every element, so a resource
+     * un-shared or a membership ended stops the stream rather than continuing to
+     * push. Same shape and same semantics as a query's.
+     */
+    readonly guards?: Guards;
 }) => StreamProcedureDescriptor<Name, Input, Element, Error>;
 
 export declare interface DeleteTarget<Input = unknown> extends NestedTargetFields<Input> {
@@ -878,6 +1038,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 +1066,285 @@ 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;
+    /** 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 +1402,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 +1586,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 +1620,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;
 
@@ -1189,6 +1661,28 @@ export declare interface MutationProcedureDescriptor<Name extends string, Input
     readonly exposeAsTool: ExposeAsTool | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -1235,6 +1729,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 +1771,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
@@ -2083,6 +2619,28 @@ export declare interface QueryProcedureDescriptor<Name extends string, Input ext
     readonly exposeAsTool: ExposeAsTool | undefined;
     /** True when the procedure is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
+    /**
+     * Replace a PLUGIN route that answers to this same tag.
+     *
+     * Without it, a user route and a plugin route sharing a tag is a hard error,
+     * and correctly so — two handlers behind one name is not a thing a caller can
+     * reason about. But refusing is the wrong answer when the app deliberately
+     * wants its own version: the two escapes available otherwise are to rename
+     * your procedure (so the split runs along "who built it" rather than along a
+     * domain boundary) or to `alias` the whole plugin away (same, one level up).
+     * For a frontend developer that is the worst possible partition.
+     *
+     * A reporter wanted exactly this: adopt `@voltro/plugin-notifications`, whose
+     * surface is richer than theirs, add `archive`/`unarchive` beside it — which
+     * already composes, since the collision check compares FULL tags and not
+     * prefixes — and replace `markRead`, because theirs maintains archive state.
+     *
+     * Explicit, never inferred. Silently letting the app win would mean a plugin
+     * upgrade that adds a route could shadow an app procedure with no diff to
+     * read; declaring it makes the intent reviewable and puts the override in the
+     * file that performs it.
+     */
+    readonly overridesPlugin: boolean | undefined;
     readonly internal: boolean | undefined;
 }
 
@@ -2440,6 +2998,10 @@ export declare interface StreamProcedureDescriptor<Name extends string, Input ex
     /** True when the stream is kept OFF the wire — no client-group entry and no
      *  route in dev or serve. See `internal` on the definer's options. */
     readonly internal: boolean | undefined;
+    /** WHO MAY LISTEN. Checked at subscribe AND re-checked before every element,
+     *  the same as a query's — a stream is a long-lived grant and the scopes that
+     *  justified it can be withdrawn while it is still open. */
+    readonly guards: Guards | undefined;
 }
 
 export declare const streamToRpc: <Name extends string, Input extends Schema.Schema.Any, Element extends Schema.Schema.Any, Err extends Schema.Schema.All>(descriptor: StreamProcedureDescriptor<Name, Input, Element, Err>, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Input extends Schema.Struct.Fields ? Schema.Struct<Input> : Input, Stream<Element, Schema.Schema.All>, typeof Schema.Never, never>;
@@ -2484,36 +3046,36 @@ export declare class SubjectService extends SubjectService_base {
 
 declare const SubjectService_base: Context.TagClass<SubjectService, "@voltro/Subject", {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "user";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "apiKey";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: string;
-    readonly tenantId: string;
     readonly type: "serviceAccount";
+    readonly tenantId: string;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;
     } | undefined;
 } | {
     readonly id: null;
-    readonly tenantId: string | null;
     readonly type: "anonymous";
+    readonly tenantId: string | null;
 } | {
     readonly id: string;
-    readonly tenantId: null;
     readonly type: "system";
+    readonly tenantId: null;
     readonly scopes?: readonly string[] | undefined;
     readonly metadata?: {
         readonly [x: string]: unknown;