@super-line/server 0.9.0 → 0.10.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, AccessRules, Resource, Perms, ServerReplica, SharedTopics, EventData, ServerTransport, Handshake, ServerStore } from '@super-line/core';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -132,13 +132,21 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
-    kind: 'request' | 'subscribe' | 'event';
-    /** The request/topic/event name. */
+    /**
+     * The operation kind. Middleware only ever sees `'request'`/`'subscribe'`; `'event'` marks a bus
+     * event delivery, and `'connect'`/`'disconnect'` mark a lifecycle-hook throw routed to `onError`.
+     */
+    kind: 'request' | 'subscribe' | 'event' | 'connect' | 'disconnect';
+    /** The request/topic/event name (the hook name for lifecycle errors). */
     name: string;
     /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
     conn?: Conn;
 }
+/**
+ * A plugin's flat middleware — like {@link Middleware} but `ctx` is `unknown` (a plugin is written
+ * independently of the host's per-role ctx). Concatenated after the host chain, in plugin array order.
+ */
+type PluginMiddleware = (ctx: unknown, info: MiddlewareInfo, next: () => Promise<void>) => Awaitable<void>;
 /** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
 interface BusMeta {
     /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
@@ -241,8 +249,13 @@ interface ServerStoreHandle {
     revoke(id: string, principal: string): Promise<void>;
     /** Delete a Resource. */
     delete(id: string): Promise<void>;
-    /** All Resource ids in this store. */
-    list(): Promise<string[]>;
+    /**
+     * Summaries of this store's Resources, server-side filtered / sorted / paginated per {@link ListOpts}
+     * (omit `opts` for every Resource, id-ascending). Forwards to {@link ServerStore.list}.
+     */
+    list(opts?: ListOpts): Promise<ResourceSummary[]>;
+    /** Distinct principals granted anywhere in this store (store-global). Forwards to {@link ServerStore.searchPrincipals}. */
+    searchPrincipals(opts: SearchOpts): Promise<string[]>;
     /**
      * Open a reactive in-process co-writer over a Resource's canonical state — the server half's mirror of
      * `client.store(name).open(id)`. Reactive reads, merging `update`, and surgical `delete(path)` (the only
@@ -253,8 +266,158 @@ interface ServerStoreHandle {
         origin?: string;
     }): ServerReplica;
 }
+/**
+ * Handlers a plugin provides for its paired surface `S` (ADR-0004): one per `clientToServer` key,
+ * typed from `S`. `ctx`/`conn` are loose — a plugin is written independently of the host's per-role ctx.
+ */
+type HandlersFor<S extends Directional> = {
+    [K in keyof CtsOf<S>]: (input: ServerInput<CtsOf<S>[K]>, ctx: unknown, conn: Conn) => Awaitable<Output<CtsOf<S>[K]>>;
+};
+/** Keys one plugin handles; a naked param so a multi-plugin `P[number]` union distributes per-plugin. */
+type PluginHandledKeys<U> = U extends SuperLinePlugin<infer S> ? keyof CtsOf<S> & string : never;
+/** Union of the `clientToServer` keys handled across a plugin tuple `P` (subtracted from `implement`). */
+type HandledKeys<P extends readonly SuperLinePlugin<any>[]> = PluginHandledKeys<P[number]>;
+/** Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. */
+type SubtractHandlers<H, HK extends string> = {
+    [B in keyof H]: Omit<H[B], HK>;
+};
+/**
+ * A named, declarative bundle of runtime contributions registered on `plugins: [...]`. All fields
+ * are optional; a plugin ships as a pair (this server half + an optional client half). See ADR-0005.
+ * The optional type param `S` is the plugin's paired surface — its `handlers` compile against `S`, and
+ * `S`'s `clientToServer` keys are subtracted from the host's `implement()` obligation at compile time.
+ */
+interface SuperLinePlugin<S extends Directional = {}> {
+    /** Unique among the server's plugins; a duplicate name throws at construction. */
+    name: string;
+    /**
+     * Node-local tap fired synchronously at each emit site with LIVE payload references (an observer
+     * must not mutate them). Reuses the {@link TapEvent} taxonomy; zero cost when no plugin taps. A
+     * throwing tap is isolated and routed to `onError` — it never fails the underlying operation.
+     */
+    onEvent?: (event: TapEvent) => void;
+    /** Middleware run before request/subscribe handlers, after the host chain, in plugin array order. */
+    use?: PluginMiddleware[];
+    /** Called once per accepted connection (multiplexed after the host's `onConnection`). */
+    onConnection?: (conn: Conn, ctx: unknown) => void;
+    /** Called when a connection closes (multiplexed after the host's `onDisconnect`). */
+    onDisconnect?: (conn: Conn, ctx: unknown, code: number) => void;
+    /** Receives any error thrown in middleware/handlers/hooks (multiplexed with the host's `onError`). */
+    onError?: (error: unknown, info: MiddlewareInfo) => void;
+    /**
+     * Request handlers for the plugin's paired surface `S`, built lazily with the {@link PluginContext}.
+     * Merged into dispatch under their method names; the host merges `S` into a role and these keys are
+     * subtracted from its `implement()` obligation. A key already handled by the host (or another plugin)
+     * throws at construction.
+     */
+    handlers?: (ctx: PluginContext) => HandlersFor<S>;
+    /**
+     * Server halves of Store pairs the plugin contributes, merged into the host's `stores` and reachable
+     * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
+     */
+    stores?: Record<string, ServerStore>;
+    /**
+     * A plugin-owned (reserved) connection class — its own role, handshake negotiation, and parallel contract,
+     * served over observer-invisible connections. See {@link PluginConnection}. (Phase 2.)
+     */
+    connection?: PluginConnection;
+    /**
+     * Imperative escape hatch, run once at construction with the plugin's {@link PluginContext}. Return
+     * an optional dispose function, called on `server.close()`. Use for wiring cluster-wide views from
+     * local taps + a plugin channel (the inspector's pattern), timers, or background subscriptions.
+     */
+    setup?: (ctx: PluginContext) => void | (() => void);
+}
+/**
+ * A plugin-owned connection class (ADR-0005 phase 2): a reserved role the transport negotiates (never one
+ * of the user contract's roles), dispatched against the plugin's own fixed `contract` — never merged into
+ * the user's. Matching conns are observer-invisible (excluded from conns/presence/heartbeat/user hooks).
+ * The inspector's Control-Center channel is one such class.
+ */
+interface PluginConnection {
+    /** The reserved role; must be unique across the server (user roles + other reserved classes). */
+    role: string;
+    /** WebSocket subprotocol to advertise + match (browsers set this where they can't set headers). */
+    subprotocol?: string;
+    /** Predicate for transports without a subprotocol (SSE/libp2p): match on the normalized handshake. */
+    match?: (handshake: Handshake) => boolean;
+    /** The parallel contract these connections speak (its `clientToServer` = requests, `subscribe` topics = feeds). */
+    contract: Contract;
+    /**
+     * Request handlers for `contract`'s `clientToServer`, built with the {@link PluginContext}. A subscribe to
+     * one of `contract`'s topics bridges the conn to the plugin's {@link PluginChannel} of the same name.
+     */
+    handlers?: (ctx: PluginContext) => Record<string, (input: unknown, conn: Conn) => Awaitable<unknown>>;
+}
+/** A plugin-private adapter channel (reserved `x:<plugin>:` prefix), fanned out cluster-wide. */
+interface PluginChannel {
+    /** Publish to this channel; delivered to every node's subscribers (local echo included). */
+    publish(data: unknown): void;
+    /** Subscribe to this channel. `meta.from` is the publishing node. Returns an unsubscribe fn. */
+    subscribe(handler: (data: unknown, meta: BusMeta) => void): () => void;
+}
+/**
+ * The capabilities handed to a plugin's `setup`/`handlers`: the server's public surface minus the
+ * footguns (`implement`/`close`), plus a privileged block — a plugin-private adapter {@link PluginChannel},
+ * node identity, the serializer, a read-only conns view, and the raw contract for reflection. Sized to
+ * the inspector's audited needs; grows case-by-case.
+ */
+interface PluginContext {
+    /** This node's stable id (equals `srv.nodeId`). */
+    readonly nodeId: string;
+    /** This node's friendly name (equals `srv.nodeName`). */
+    readonly nodeName: string;
+    /** Alias of {@link PluginContext.nodeId} — the per-process instance id used to tag cluster fan-out. */
+    readonly instanceId: string;
+    /** The wire serializer configured on the server. */
+    readonly serializer: Serializer;
+    /** The raw contract, for reflection (e.g. `classifyContract`). */
+    readonly contract: Contract;
+    /** Connections accepted on THIS node (read-only snapshot; excludes reserved conns). */
+    readonly conns: readonly Conn[];
+    /** Node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Cluster-wide presence introspection (rejects without a presence-capable adapter). */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Publish a shared topic (server-only publish). */
+    publish(topic: string, data: unknown): void;
+    /** Subscribe server-side to a shared topic, cluster-wide (local echo). Returns an unsubscribe fn. */
+    subscribe(topic: string, handler: (data: unknown, meta: BusMeta) => void): () => void;
+    /** Target a single connection by id, on whatever node holds it. */
+    toConn(id: string): {
+        emit(event: string, data: unknown): void;
+        close(): void;
+    };
+    /** Target all of a user's connections across nodes. */
+    toUser(userId: string): {
+        emit(event: string, data: unknown): void;
+        disconnect(): void;
+    };
+    /** Server-controlled room membership + broadcast (loosely typed, mirroring toConn/toUser). */
+    room(name: string): {
+        add(conn: Conn): void;
+        remove(conn: Conn): void;
+        broadcast(event: string, data: unknown): void;
+        readonly size: number;
+        readonly connections: readonly Conn[];
+    };
+    /** Server-authoritative handle for a configured store (incl. plugin-contributed stores). */
+    store(name: string): ServerStoreHandle;
+    /** Configured stores (host + plugin) and their models. */
+    storeInfos(): StoreInfo[];
+    /** Full cluster descriptor for a local connection (identity + rooms + `describeConn` extras). */
+    describe(conn: Conn): ConnDescriptor;
+    /** A connection's descriptor anywhere in the cluster (rejects without presence support); undefined if absent. */
+    connectionById(id: string): Promise<ConnDescriptor | undefined>;
+    /** A plugin-private, cluster-wide adapter channel under the reserved `x:<plugin>:` prefix. */
+    channel(name: string): PluginChannel;
+}
 /** Options for {@link createSuperLineServer}. */
-interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P extends readonly SuperLinePlugin<any>[] = readonly SuperLinePlugin<any>[]> {
+    /** Named runtime bundles (taps, middleware, lifecycle, handlers, stores). See {@link SuperLinePlugin}. */
+    plugins?: P;
     /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
     transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -286,14 +449,6 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /**
-     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
-     * clients. The WS transport must also be created with `inspector: true` to negotiate the
-     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
-     */
-    inspector?: boolean | {
-        redact?: string[];
-    };
     /**
      * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
      * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
@@ -308,7 +463,7 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
 /** A running super-line server, returned by {@link createSuperLineServer}. */
-interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extends string = never> {
     /** This node's stable id (unique per server process). */
     readonly nodeId: string;
     /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
@@ -323,8 +478,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     toConn(id: string): ConnTarget<C>;
     /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
     toUser(userId: string): UserTarget<C>;
-    /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
+    /** Register handlers for shared + per-role requests (chainable). Keys handled by a plugin (`HK`) are subtracted. */
+    implement(handlers: SubtractHandlers<Handlers<C, A>, HK>): SuperLineServer<C, A, HK>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
@@ -364,6 +519,6 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
+declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>, const P extends readonly SuperLinePlugin<any>[] = []>(contract: C, opts: SuperLineServerOptions<C, A, P>): SuperLineServer<C, A, HandledKeys<P>>;
 
-export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerStoreHandle, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, AccessRules, Resource, Perms, ServerReplica, SharedTopics, EventData, ServerTransport, Handshake, ServerStore } from '@super-line/core';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, Directional, TapEvent, AccessRules, Resource, Perms, ListOpts, ResourceSummary, SearchOpts, ServerReplica, StoreInfo, CtsOf, ServerInput, ServerStore, Handshake, SharedRequests, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport } from '@super-line/core';
 
 /**
  * A single client connection, passed to handlers as the third argument.
@@ -132,13 +132,21 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
-    kind: 'request' | 'subscribe' | 'event';
-    /** The request/topic/event name. */
+    /**
+     * The operation kind. Middleware only ever sees `'request'`/`'subscribe'`; `'event'` marks a bus
+     * event delivery, and `'connect'`/`'disconnect'` mark a lifecycle-hook throw routed to `onError`.
+     */
+    kind: 'request' | 'subscribe' | 'event' | 'connect' | 'disconnect';
+    /** The request/topic/event name (the hook name for lifecycle errors). */
     name: string;
     /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
     conn?: Conn;
 }
+/**
+ * A plugin's flat middleware — like {@link Middleware} but `ctx` is `unknown` (a plugin is written
+ * independently of the host's per-role ctx). Concatenated after the host chain, in plugin array order.
+ */
+type PluginMiddleware = (ctx: unknown, info: MiddlewareInfo, next: () => Promise<void>) => Awaitable<void>;
 /** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
 interface BusMeta {
     /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
@@ -241,8 +249,13 @@ interface ServerStoreHandle {
     revoke(id: string, principal: string): Promise<void>;
     /** Delete a Resource. */
     delete(id: string): Promise<void>;
-    /** All Resource ids in this store. */
-    list(): Promise<string[]>;
+    /**
+     * Summaries of this store's Resources, server-side filtered / sorted / paginated per {@link ListOpts}
+     * (omit `opts` for every Resource, id-ascending). Forwards to {@link ServerStore.list}.
+     */
+    list(opts?: ListOpts): Promise<ResourceSummary[]>;
+    /** Distinct principals granted anywhere in this store (store-global). Forwards to {@link ServerStore.searchPrincipals}. */
+    searchPrincipals(opts: SearchOpts): Promise<string[]>;
     /**
      * Open a reactive in-process co-writer over a Resource's canonical state — the server half's mirror of
      * `client.store(name).open(id)`. Reactive reads, merging `update`, and surgical `delete(path)` (the only
@@ -253,8 +266,158 @@ interface ServerStoreHandle {
         origin?: string;
     }): ServerReplica;
 }
+/**
+ * Handlers a plugin provides for its paired surface `S` (ADR-0004): one per `clientToServer` key,
+ * typed from `S`. `ctx`/`conn` are loose — a plugin is written independently of the host's per-role ctx.
+ */
+type HandlersFor<S extends Directional> = {
+    [K in keyof CtsOf<S>]: (input: ServerInput<CtsOf<S>[K]>, ctx: unknown, conn: Conn) => Awaitable<Output<CtsOf<S>[K]>>;
+};
+/** Keys one plugin handles; a naked param so a multi-plugin `P[number]` union distributes per-plugin. */
+type PluginHandledKeys<U> = U extends SuperLinePlugin<infer S> ? keyof CtsOf<S> & string : never;
+/** Union of the `clientToServer` keys handled across a plugin tuple `P` (subtracted from `implement`). */
+type HandledKeys<P extends readonly SuperLinePlugin<any>[]> = PluginHandledKeys<P[number]>;
+/** Remove the plugin-handled keys `HK` from every block (each role + `shared`) of a {@link Handlers} map. */
+type SubtractHandlers<H, HK extends string> = {
+    [B in keyof H]: Omit<H[B], HK>;
+};
+/**
+ * A named, declarative bundle of runtime contributions registered on `plugins: [...]`. All fields
+ * are optional; a plugin ships as a pair (this server half + an optional client half). See ADR-0005.
+ * The optional type param `S` is the plugin's paired surface — its `handlers` compile against `S`, and
+ * `S`'s `clientToServer` keys are subtracted from the host's `implement()` obligation at compile time.
+ */
+interface SuperLinePlugin<S extends Directional = {}> {
+    /** Unique among the server's plugins; a duplicate name throws at construction. */
+    name: string;
+    /**
+     * Node-local tap fired synchronously at each emit site with LIVE payload references (an observer
+     * must not mutate them). Reuses the {@link TapEvent} taxonomy; zero cost when no plugin taps. A
+     * throwing tap is isolated and routed to `onError` — it never fails the underlying operation.
+     */
+    onEvent?: (event: TapEvent) => void;
+    /** Middleware run before request/subscribe handlers, after the host chain, in plugin array order. */
+    use?: PluginMiddleware[];
+    /** Called once per accepted connection (multiplexed after the host's `onConnection`). */
+    onConnection?: (conn: Conn, ctx: unknown) => void;
+    /** Called when a connection closes (multiplexed after the host's `onDisconnect`). */
+    onDisconnect?: (conn: Conn, ctx: unknown, code: number) => void;
+    /** Receives any error thrown in middleware/handlers/hooks (multiplexed with the host's `onError`). */
+    onError?: (error: unknown, info: MiddlewareInfo) => void;
+    /**
+     * Request handlers for the plugin's paired surface `S`, built lazily with the {@link PluginContext}.
+     * Merged into dispatch under their method names; the host merges `S` into a role and these keys are
+     * subtracted from its `implement()` obligation. A key already handled by the host (or another plugin)
+     * throws at construction.
+     */
+    handlers?: (ctx: PluginContext) => HandlersFor<S>;
+    /**
+     * Server halves of Store pairs the plugin contributes, merged into the host's `stores` and reachable
+     * via `srv.store(name)`. A name colliding with a host store or another plugin's store throws at construction.
+     */
+    stores?: Record<string, ServerStore>;
+    /**
+     * A plugin-owned (reserved) connection class — its own role, handshake negotiation, and parallel contract,
+     * served over observer-invisible connections. See {@link PluginConnection}. (Phase 2.)
+     */
+    connection?: PluginConnection;
+    /**
+     * Imperative escape hatch, run once at construction with the plugin's {@link PluginContext}. Return
+     * an optional dispose function, called on `server.close()`. Use for wiring cluster-wide views from
+     * local taps + a plugin channel (the inspector's pattern), timers, or background subscriptions.
+     */
+    setup?: (ctx: PluginContext) => void | (() => void);
+}
+/**
+ * A plugin-owned connection class (ADR-0005 phase 2): a reserved role the transport negotiates (never one
+ * of the user contract's roles), dispatched against the plugin's own fixed `contract` — never merged into
+ * the user's. Matching conns are observer-invisible (excluded from conns/presence/heartbeat/user hooks).
+ * The inspector's Control-Center channel is one such class.
+ */
+interface PluginConnection {
+    /** The reserved role; must be unique across the server (user roles + other reserved classes). */
+    role: string;
+    /** WebSocket subprotocol to advertise + match (browsers set this where they can't set headers). */
+    subprotocol?: string;
+    /** Predicate for transports without a subprotocol (SSE/libp2p): match on the normalized handshake. */
+    match?: (handshake: Handshake) => boolean;
+    /** The parallel contract these connections speak (its `clientToServer` = requests, `subscribe` topics = feeds). */
+    contract: Contract;
+    /**
+     * Request handlers for `contract`'s `clientToServer`, built with the {@link PluginContext}. A subscribe to
+     * one of `contract`'s topics bridges the conn to the plugin's {@link PluginChannel} of the same name.
+     */
+    handlers?: (ctx: PluginContext) => Record<string, (input: unknown, conn: Conn) => Awaitable<unknown>>;
+}
+/** A plugin-private adapter channel (reserved `x:<plugin>:` prefix), fanned out cluster-wide. */
+interface PluginChannel {
+    /** Publish to this channel; delivered to every node's subscribers (local echo included). */
+    publish(data: unknown): void;
+    /** Subscribe to this channel. `meta.from` is the publishing node. Returns an unsubscribe fn. */
+    subscribe(handler: (data: unknown, meta: BusMeta) => void): () => void;
+}
+/**
+ * The capabilities handed to a plugin's `setup`/`handlers`: the server's public surface minus the
+ * footguns (`implement`/`close`), plus a privileged block — a plugin-private adapter {@link PluginChannel},
+ * node identity, the serializer, a read-only conns view, and the raw contract for reflection. Sized to
+ * the inspector's audited needs; grows case-by-case.
+ */
+interface PluginContext {
+    /** This node's stable id (equals `srv.nodeId`). */
+    readonly nodeId: string;
+    /** This node's friendly name (equals `srv.nodeName`). */
+    readonly nodeName: string;
+    /** Alias of {@link PluginContext.nodeId} — the per-process instance id used to tag cluster fan-out. */
+    readonly instanceId: string;
+    /** The wire serializer configured on the server. */
+    readonly serializer: Serializer;
+    /** The raw contract, for reflection (e.g. `classifyContract`). */
+    readonly contract: Contract;
+    /** Connections accepted on THIS node (read-only snapshot; excludes reserved conns). */
+    readonly conns: readonly Conn[];
+    /** Node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Cluster-wide presence introspection (rejects without a presence-capable adapter). */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Publish a shared topic (server-only publish). */
+    publish(topic: string, data: unknown): void;
+    /** Subscribe server-side to a shared topic, cluster-wide (local echo). Returns an unsubscribe fn. */
+    subscribe(topic: string, handler: (data: unknown, meta: BusMeta) => void): () => void;
+    /** Target a single connection by id, on whatever node holds it. */
+    toConn(id: string): {
+        emit(event: string, data: unknown): void;
+        close(): void;
+    };
+    /** Target all of a user's connections across nodes. */
+    toUser(userId: string): {
+        emit(event: string, data: unknown): void;
+        disconnect(): void;
+    };
+    /** Server-controlled room membership + broadcast (loosely typed, mirroring toConn/toUser). */
+    room(name: string): {
+        add(conn: Conn): void;
+        remove(conn: Conn): void;
+        broadcast(event: string, data: unknown): void;
+        readonly size: number;
+        readonly connections: readonly Conn[];
+    };
+    /** Server-authoritative handle for a configured store (incl. plugin-contributed stores). */
+    store(name: string): ServerStoreHandle;
+    /** Configured stores (host + plugin) and their models. */
+    storeInfos(): StoreInfo[];
+    /** Full cluster descriptor for a local connection (identity + rooms + `describeConn` extras). */
+    describe(conn: Conn): ConnDescriptor;
+    /** A connection's descriptor anywhere in the cluster (rejects without presence support); undefined if absent. */
+    connectionById(id: string): Promise<ConnDescriptor | undefined>;
+    /** A plugin-private, cluster-wide adapter channel under the reserved `x:<plugin>:` prefix. */
+    channel(name: string): PluginChannel;
+}
 /** Options for {@link createSuperLineServer}. */
-interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>, P extends readonly SuperLinePlugin<any>[] = readonly SuperLinePlugin<any>[]> {
+    /** Named runtime bundles (taps, middleware, lifecycle, handlers, stores). See {@link SuperLinePlugin}. */
+    plugins?: P;
     /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
     transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -286,14 +449,6 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /**
-     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
-     * clients. The WS transport must also be created with `inspector: true` to negotiate the
-     * `superline.inspector.v1` subprotocol. **Default off; dev / trusted-network only.**
-     */
-    inspector?: boolean | {
-        redact?: string[];
-    };
     /**
      * Pluggable persisted-state Stores, keyed by name (`{ scene: crdtStoreServer(), config: memoryStoreServer() }`).
      * Each is the server half of a Store pair; the client passes the matching client halves. Surfaced as
@@ -308,7 +463,7 @@ interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
 /** A running super-line server, returned by {@link createSuperLineServer}. */
-interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>, HK extends string = never> {
     /** This node's stable id (unique per server process). */
     readonly nodeId: string;
     /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
@@ -323,8 +478,8 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
     toConn(id: string): ConnTarget<C>;
     /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
     toUser(userId: string): UserTarget<C>;
-    /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
+    /** Register handlers for shared + per-role requests (chainable). Keys handled by a plugin (`HK`) are subtracted. */
+    implement(handlers: SubtractHandlers<Handlers<C, A>, HK>): SuperLineServer<C, A, HK>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
@@ -364,6 +519,6 @@ interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
+declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>, const P extends readonly SuperLinePlugin<any>[] = []>(contract: C, opts: SuperLineServerOptions<C, A, P>): SuperLineServer<C, A, HandledKeys<P>>;
 
-export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerStoreHandle, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };
+export { type AuthResult, type BusMeta, type ClusterView, Conn, type ConnTarget, type HandledKeys, type Handlers, type HandlersFor, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type PluginChannel, type PluginConnection, type PluginContext, type PluginMiddleware, type RoleLens, type Room, type ServerStoreHandle, type SubtractHandlers, type SuperLinePlugin, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer, resolvePrincipal };