@super-line/core 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @super-line/core
 
-Shared core for [**super-line**](https://mertdogar.github.io/super-line/) — end-to-end typesafe WebSockets for TypeScript. This package holds the pieces both ends import: `defineContract`, runtime validation, the `SocketError` model, and the `Serializer` / `Adapter` interfaces.
+Shared core for [**super-line**](https://mertdogar.github.io/super-line/) — end-to-end typesafe WebSockets for TypeScript. This package holds the pieces both ends import: `defineContract`, runtime validation, the `SuperLineError` model, and the `Serializer` / `Adapter` interfaces.
 
 ```bash
 pnpm add @super-line/core zod

package/dist/index.cjs

@@ -20,8 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  INSPECTOR_ROLE: () => INSPECTOR_ROLE,
+  INSPECTOR_SUBPROTOCOL: () => INSPECTOR_SUBPROTOCOL,
+  InspectorContract: () => InspectorContract,
   PROTOCOL: () => PROTOCOL,
-  SocketError: () => SocketError,
+  SuperLineError: () => SuperLineError,
+  classifyContract: () => classifyContract,
   defineContract: () => defineContract,
   jsonSerializer: () => jsonSerializer,
   validate: () => validate,
@@ -30,19 +34,19 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SocketError = class extends Error {
+var SuperLineError = class extends Error {
   /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
   code;
   /** Optional structured data attached to the error, delivered to the client. */
   data;
   /**
-   * @param code - a {@link SocketErrorCode} or custom string.
+   * @param code - a {@link SuperLineErrorCode} or custom string.
    * @param message - human-readable message (defaults to `code`).
    * @param data - optional structured payload delivered to the client.
    */
   constructor(code, message, data) {
     super(message ?? code);
-    this.name = "SocketError";
+    this.name = "SuperLineError";
     this.code = code;
     this.data = data;
   }
@@ -63,27 +67,100 @@ async function validate(schema, value) {
   let result = schema["~standard"].validate(value);
   if (result instanceof Promise) result = await result;
   if (result.issues) {
-    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+    throw new SuperLineError("VALIDATION", "Validation failed", result.issues);
   }
   return result.value;
 }
 function validateSync(schema, value) {
   const result = schema["~standard"].validate(value);
   if (result instanceof Promise) {
-    throw new SocketError("INTERNAL", "Async schema not supported for synchronous validation");
+    throw new SuperLineError("INTERNAL", "Async schema not supported for synchronous validation");
   }
   if (result.issues) {
-    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+    throw new SuperLineError("VALIDATION", "Validation failed", result.issues);
   }
   return result.value;
 }
 
+// src/inspector.ts
+var INSPECTOR_SUBPROTOCOL = "superline.inspector.v1";
+var INSPECTOR_ROLE = "inspector";
+function s() {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "super-line-inspector",
+      validate: (value) => ({ value })
+    }
+  };
+}
+var InspectorContract = defineContract({
+  roles: {
+    inspector: {
+      clientToServer: {
+        getContract: { input: s(), output: s() },
+        getTopology: { input: s(), output: s() },
+        listConnections: { input: s(), output: s() },
+        getNode: { input: s(), output: s() },
+        getConn: { input: s(), output: s() }
+      },
+      serverToClient: {
+        events: { payload: s(), subscribe: true }
+      }
+    }
+  }
+});
+function withSchemas(msg, schemas, convert) {
+  if (!convert) return msg;
+  for (const [key, schema] of Object.entries(schemas)) {
+    const value = convert(schema);
+    if (value !== void 0) msg[key] = value;
+  }
+  return msg;
+}
+function classifyDirectional(d, convert) {
+  const clientToServer = [];
+  const serverToClient = [];
+  for (const [name, def] of Object.entries(d?.clientToServer ?? {})) {
+    clientToServer.push(
+      withSchemas({ name, flavor: "request" }, { input: def.input, output: def.output }, convert)
+    );
+  }
+  for (const [name, def] of Object.entries(d?.serverToClient ?? {})) {
+    if ("input" in def) {
+      serverToClient.push(
+        withSchemas({ name, flavor: "serverRequest" }, { input: def.input, output: def.output }, convert)
+      );
+    } else {
+      serverToClient.push(
+        withSchemas(
+          { name, flavor: def.subscribe === true ? "topic" : "event" },
+          { payload: def.payload },
+          convert
+        )
+      );
+    }
+  }
+  return { clientToServer, serverToClient };
+}
+function classifyContract(contract, convert) {
+  const roles = {};
+  for (const [role, block] of Object.entries(contract.roles)) {
+    roles[role] = classifyDirectional(block, convert);
+  }
+  return { shared: classifyDirectional(contract.shared, convert), roles };
+}
+
 // src/wire.ts
 var PROTOCOL = "superline.v1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  INSPECTOR_ROLE,
+  INSPECTOR_SUBPROTOCOL,
+  InspectorContract,
   PROTOCOL,
-  SocketError,
+  SuperLineError,
+  classifyContract,
   defineContract,
   jsonSerializer,
   validate,

package/dist/index.d.cts

@@ -1,21 +1,21 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /** The built-in error codes super-line uses across the wire. */
-type SocketErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
+type SuperLineErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
 /** A built-in code or any custom string (autocomplete keeps the known set). */
-type ErrorCode = SocketErrorCode | (string & {});
+type ErrorCode = SuperLineErrorCode | (string & {});
 /**
  * The error type carried end-to-end. Throw one from a handler and the client's
  * promise rejects with the same `code` (and optional `data`). Unknown throws
  * become `INTERNAL` so server internals aren't leaked.
  */
-declare class SocketError<Data = unknown> extends Error {
+declare class SuperLineError<Data = unknown> extends Error {
     /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
     readonly code: ErrorCode;
     /** Optional structured data attached to the error, delivered to the client. */
     readonly data?: Data;
     /**
-     * @param code - a {@link SocketErrorCode} or custom string.
+     * @param code - a {@link SuperLineErrorCode} or custom string.
      * @param message - human-readable message (defaults to `code`).
      * @param data - optional structured payload delivered to the client.
      */
@@ -36,8 +36,8 @@ interface Serializer {
 declare const jsonSerializer: Serializer;
 
 /**
- * Cross-node fan-out seam. Rooms, topics, and serverToServer all compile down to
- * channel pub/sub. A node subscribes to a channel only while it has a local member,
+ * Cross-node fan-out seam. Rooms, topics, and the cluster event bus all compile down
+ * to channel pub/sub. A node subscribes to a channel only while it has a local member,
  * and publishes always go through the adapter (the in-memory adapter loops back),
  * so a node delivers to its local members on receipt — one code path, no double-send.
  *
@@ -55,6 +55,75 @@ interface Adapter {
     onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
     /** Optional teardown (e.g. close Redis connections). */
     close?(): void | Promise<void>;
+    /**
+     * Optional cluster-wide presence directory. Powers `srv.cluster.*` and
+     * `srv.isOnline`. The in-memory and Redis adapters implement it; cluster
+     * queries throw a clear error on an adapter that doesn't.
+     */
+    presence?: PresenceStore;
+}
+/** A serializable snapshot of a connection, shared cluster-wide via the {@link PresenceStore}. */
+interface ConnDescriptor {
+    /** The connection's server-assigned id. */
+    id: string;
+    /** The connection's role. */
+    role: string;
+    /** The node that holds this connection. */
+    nodeId: string;
+    /** The node's friendly name (defaults to a short slice of `nodeId`). */
+    nodeName: string;
+    /** When the connection was accepted (`Date.now()`). */
+    connectedAt: number;
+    /** The stable user key from the server's `identify` hook, if any. */
+    userId?: string;
+    /** Room memberships (topics and node-local `lastPongAt` are not included). */
+    rooms: string[];
+    /** Extra fields contributed by the server's `describeConn` hook. */
+    [extra: string]: unknown;
+}
+/** Per-node aggregate, returned by {@link PresenceStore.topology}. */
+interface NodeStat {
+    /** The node's id. */
+    nodeId: string;
+    /** The node's friendly name (defaults to a short slice of `nodeId`). */
+    nodeName: string;
+    /** Number of connections on the node. */
+    connections: number;
+    /** Number of distinct rooms with members on the node. */
+    rooms: number;
+    /** Whether the node is currently live (heartbeat fresh). */
+    alive: boolean;
+}
+/**
+ * Cluster-wide presence directory: a query/addressbook layer kept in the shared
+ * substrate (in-memory bus or Redis). Live message delivery does NOT read this —
+ * it exists only to answer `srv.cluster.*` / `srv.isOnline`.
+ */
+interface PresenceStore {
+    /** Record (or replace) a connection's descriptor. */
+    set(descriptor: ConnDescriptor): void | Promise<void>;
+    /** Remove a connection's descriptor. */
+    del(connId: string): void | Promise<void>;
+    /** Refresh this node's liveness (heartbeat). */
+    beat(nodeId: string): void | Promise<void>;
+    /** Remove all of a node's connections + liveness (graceful shutdown cleanup). */
+    clearNode(nodeId: string): void | Promise<void>;
+    /** Add a room to a connection's membership. */
+    addRoom(connId: string, room: string): void | Promise<void>;
+    /** Remove a room from a connection's membership. */
+    removeRoom(connId: string, room: string): void | Promise<void>;
+    /** All live connection descriptors across the cluster. */
+    list(): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** One connection's descriptor, if present. */
+    get(connId: string): (ConnDescriptor | undefined) | Promise<ConnDescriptor | undefined>;
+    /** Descriptors for a given user key. */
+    byUser(userId: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Descriptors that are members of `room`. */
+    roomMembers(room: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): number | Promise<number>;
+    /** Per-node aggregates. */
+    topology(): NodeStat[] | Promise<NodeStat[]>;
 }
 
 /** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
@@ -80,25 +149,41 @@ interface ServerMessageDef {
     /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
     subscribe?: boolean;
 }
+/**
+ * A server→client request (request/response). The server sends `input`; the
+ * client's `implement` handler returns `output`. Lives in `serverToClient`
+ * alongside events and topics, distinguished by having `input`.
+ */
+interface ServerRequestDef {
+    /** Schema for the request payload the server sends. */
+    input: Schema;
+    /** Schema for the reply the client returns. */
+    output: Schema;
+}
+/** A `serverToClient` entry: a push event, a subscribable topic, or a server→client request. */
+type ServerEntry = ServerMessageDef | ServerRequestDef;
 /** The two directions within a `shared` or role block. */
 interface Directional {
     /** Requests this side may call (client→server). */
     clientToServer?: Record<string, RequestDef>;
-    /** Events/topics this side may receive (server→client). */
-    serverToClient?: Record<string, ServerMessageDef>;
+    /** Events, topics, and server→client requests this side may receive. */
+    serverToClient?: Record<string, ServerEntry>;
+}
+/** A role block: its directions plus an optional `data` schema typing `conn.data`. */
+interface RoleBlock extends Directional {
+    /** Schema for this role's mutable per-connection `conn.data` (server-side scratch state). */
+    data?: Schema;
 }
 /**
  * The single source of truth, imported by both server and client. Split by
  * **direction** and scoped by **role**: a `shared` base every role inherits,
- * plus one block per role. `serverToServer` is node↔node (not role-scoped).
+ * plus one block per role.
  */
 interface Contract {
     /** Surface common to every role (merged into each role's effective surface). */
     shared?: Directional;
     /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
-    roles: Record<string, Directional>;
-    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
-    serverToServer?: Record<string, Schema>;
+    roles: Record<string, RoleBlock>;
 }
 /**
  * Define a contract. An identity function — `const` preserves literal keys and
@@ -118,7 +203,6 @@ interface Contract {
  *     user:  { clientToServer: { say:      { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
  *     agent: { clientToServer: { announce: { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
  *   },
- *   serverToServer: { rebalance: z.object({ shard: z.number() }) },
  * })
  * ```
  */
@@ -129,10 +213,12 @@ type CtsOf<D> = D extends {
     clientToServer: infer M extends Record<string, RequestDef>;
 } ? M : {};
 type StcOf<D> = D extends {
-    serverToClient: infer M extends Record<string, ServerMessageDef>;
+    serverToClient: infer M extends Record<string, ServerEntry>;
 } ? M : {};
 type EventsOf<M> = {
     [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? never : M[K] extends {
         subscribe: true;
     } ? never : K]: M[K];
 };
@@ -141,6 +227,11 @@ type TopicsOf<M> = {
         subscribe: true;
     } ? K : never]: M[K];
 };
+type ServerReqOf<M> = {
+    [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? K : never]: M[K];
+};
 /** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
 type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
 /** A role's effective server→client map (events and topics combined). */
@@ -159,8 +250,16 @@ type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
 type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
 /** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
 type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
-/** The `serverToServer` map, or `{}` if the contract has none. */
-type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
+/** A role's effective server→client requests (`shared` ∪ `roles[R]`), answered by `client.implement`. */
+type ServerRequests<C extends Contract, R extends RoleOf<C>> = ServerReqOf<ServerMessages<C, R>>;
+/** Server→client requests in the `shared` block (the surface `srv.toConn(id).request` can call). */
+type SharedServerRequests<C extends Contract> = ServerReqOf<StcOf<C['shared']>>;
+/** The typed shape of `conn.data` for role `R` (its `data` schema, or an empty object). */
+type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
+    data: infer S extends Schema;
+} ? InferOut<S> : Record<string, never>;
+/** Union of every role's `conn.data` shape (used where the role isn't narrowed, e.g. shared handlers). */
+type AnyData<C extends Contract> = DataOf<C, RoleOf<C>>;
 /** The input type a client passes for a request (pre-validation). */
 type ClientInput<T> = T extends RequestDef ? InferIn<T['input']> : never;
 /** The input type a server handler receives for a request (post-validation). */
@@ -171,10 +270,6 @@ type Output<T> = T extends RequestDef ? InferOut<T['output']> : never;
 type EventData<T> = T extends ServerMessageDef ? InferOut<T['payload']> : never;
 /** The data a server sends for an event/topic (pre-validation). */
 type EmitData<T> = T extends ServerMessageDef ? InferIn<T['payload']> : never;
-/** The data a server sends for a serverToServer event. */
-type ServerEmit<T> = T extends Schema ? InferIn<T> : never;
-/** The data a server receives for a serverToServer event. */
-type ServerData<T> = T extends Schema ? InferOut<T> : never;
 /** Infer a schema's **input** type (what you pass into the validator). */
 type InferIn<S extends Schema> = StandardSchemaV1.InferInput<S>;
 /** Infer a schema's **output** type (the validated result). */
@@ -185,7 +280,7 @@ type InferOut<S extends Schema> = StandardSchemaV1.InferOutput<S>;
  * @param schema - the validator to run.
  * @param value - the untrusted value to validate.
  * @returns the parsed, typed value.
- * @throws {@link SocketError} with code `VALIDATION` if the value doesn't match.
+ * @throws {@link SuperLineError} with code `VALIDATION` if the value doesn't match.
  */
 declare function validate<S extends Schema>(schema: S, value: unknown): Promise<StandardSchemaV1.InferOutput<S>>;
 /**
@@ -194,10 +289,182 @@ declare function validate<S extends Schema>(schema: S, value: unknown): Promise<
  * @param schema - the validator to run.
  * @param value - the untrusted value to validate.
  * @returns the parsed, typed value.
- * @throws {@link SocketError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
+ * @throws {@link SuperLineError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
  */
 declare function validateSync<S extends Schema>(schema: S, value: unknown): StandardSchemaV1.InferOutput<S>;
 
+/** WS subprotocol the Control Center connects with; the server short-circuits auth for it. */
+declare const INSPECTOR_SUBPROTOCOL = "superline.inspector.v1";
+/** The reserved role minted for an inspector connection. */
+declare const INSPECTOR_ROLE = "inspector";
+/** How a contract message is used on the wire. */
+type MessageFlavor = 'request' | 'event' | 'topic' | 'serverRequest';
+/** One message in an {@link InspectedContract}. Schemas are best-effort JSON Schema, omitted when unavailable. */
+interface InspectedMessage {
+    /** The message name (its key in the contract). */
+    name: string;
+    /** How the message is used. */
+    flavor: MessageFlavor;
+    /** Best-effort JSON Schema of the request/server-request input. */
+    input?: unknown;
+    /** Best-effort JSON Schema of the request/server-request output. */
+    output?: unknown;
+    /** Best-effort JSON Schema of an event/topic payload. */
+    payload?: unknown;
+}
+/** The two directions of a `shared` or role block, flattened for display. */
+interface InspectedDirectional {
+    clientToServer: InspectedMessage[];
+    serverToClient: InspectedMessage[];
+}
+/** A serializable projection of a {@link Contract}'s structure — what `getContract` returns. */
+interface InspectedContract {
+    shared: InspectedDirectional;
+    roles: Record<string, InspectedDirectional>;
+}
+/** The connected node's local view — what `getNode` returns. */
+interface NodeView {
+    nodeId: string;
+    nodeName: string;
+    rooms: string[];
+    topics: string[];
+}
+/** A connection's detail — what `getConn` returns. ctx/data are node-local and best-effort safe-serialized. */
+interface ConnView {
+    descriptor: ConnDescriptor;
+    /** Safe-serialized auth ctx; present only when the conn is on the queried node. */
+    ctx?: unknown;
+    /** Safe-serialized `conn.data`; present only when the conn is on the queried node. */
+    data?: unknown;
+    /** Whether ctx/data could be read (false for conns on another node). */
+    ctxAvailable: boolean;
+}
+/** A failed response/reply, carried on `msg.response` / `msg.serverReply`. */
+interface MessageError {
+    code: string;
+    message: string;
+}
+/**
+ * A live event pushed on the `events` topic, fanned out cluster-wide. Lifecycle events
+ * (connect/disconnect/room/topic) are always emitted when inspector is on; `msg.*` events
+ * carry actual message traffic and are only emitted when inspector is on. Message payloads are
+ * safe-serialized and field-redacted (via the `inspector.redact` list) before they cross the bus.
+ */
+type InspectorEvent = {
+    type: 'connect';
+    descriptor: ConnDescriptor;
+} | {
+    type: 'disconnect';
+    connId: string;
+    nodeId: string;
+    userId?: string;
+} | {
+    type: 'room.add';
+    connId: string;
+    room: string;
+} | {
+    type: 'room.remove';
+    connId: string;
+    room: string;
+} | {
+    type: 'topic.sub';
+    connId: string;
+    topic: string;
+} | {
+    type: 'topic.unsub';
+    connId: string;
+    topic: string;
+} | {
+    type: 'msg.request';
+    connId: string;
+    role: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'msg.response';
+    connId: string;
+    name: string;
+    ok: boolean;
+    output?: unknown;
+    error?: MessageError;
+} | {
+    type: 'msg.event';
+    target: string;
+    name: string;
+    data: unknown;
+} | {
+    type: 'msg.broadcast';
+    room: string;
+    name: string;
+    data: unknown;
+} | {
+    type: 'msg.publish';
+    topic: string;
+    data: unknown;
+} | {
+    type: 'msg.serverRequest';
+    target: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'msg.serverReply';
+    target: string;
+    name: string;
+    ok: boolean;
+    output?: unknown;
+    error?: MessageError;
+};
+/**
+ * The fixed, library-owned contract describing the inspector surface. Identical for every
+ * super-line app, so it is NOT merged into the user's contract — inbound dispatch routes an
+ * inspector connection against this instead, which keeps the user's `RoleOf<C>` clean.
+ */
+declare const InspectorContract: {
+    readonly roles: {
+        readonly inspector: {
+            readonly clientToServer: {
+                readonly getContract: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<InspectedContract, InspectedContract>;
+                };
+                readonly getTopology: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<NodeStat[], NodeStat[]>;
+                };
+                readonly listConnections: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<ConnDescriptor[], ConnDescriptor[]>;
+                };
+                readonly getNode: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<NodeView, NodeView>;
+                };
+                readonly getConn: {
+                    readonly input: StandardSchemaV1<{
+                        id: string;
+                    }, {
+                        id: string;
+                    }>;
+                    readonly output: StandardSchemaV1<ConnView, ConnView>;
+                };
+            };
+            readonly serverToClient: {
+                readonly events: {
+                    readonly payload: StandardSchemaV1<InspectorEvent, InspectorEvent>;
+                    readonly subscribe: true;
+                };
+            };
+        };
+    };
+};
+/** A schema → JSON Schema converter (best-effort). Supplied by the server in slice 3. */
+type SchemaConverter = (schema: Schema) => unknown;
+/**
+ * Walk a contract and project its structure: roles × directions × message names × flavors.
+ * Pass `convert` to attach best-effort JSON Schema to each message; omit it for structure only.
+ */
+declare function classifyContract(contract: Contract, convert?: SchemaConverter): InspectedContract;
+
 /**
  * The wire protocol below is an implementation detail — you rarely touch frames
  * directly. It's exported for adapters, custom transports, and tooling.
@@ -219,7 +486,19 @@ interface UnsubFrame {
     t: 'unsub';
     c: string;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface SResFrame {
+    t: 'sres';
+    i: number;
+    d: unknown;
+}
+interface SErrFrame {
+    t: 'serr';
+    i: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -241,8 +520,15 @@ interface PubFrame {
     t: 'pub';
     c: string;
     d: unknown;
+    i?: string;
+}
+interface SReqFrame {
+    t: 'sreq';
+    i: number;
+    m: string;
+    d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };
+export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PresenceStore, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.d.ts

@@ -1,21 +1,21 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /** The built-in error codes super-line uses across the wire. */
-type SocketErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
+type SuperLineErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION' | 'DISCONNECTED' | 'INTERNAL';
 /** A built-in code or any custom string (autocomplete keeps the known set). */
-type ErrorCode = SocketErrorCode | (string & {});
+type ErrorCode = SuperLineErrorCode | (string & {});
 /**
  * The error type carried end-to-end. Throw one from a handler and the client's
  * promise rejects with the same `code` (and optional `data`). Unknown throws
  * become `INTERNAL` so server internals aren't leaked.
  */
-declare class SocketError<Data = unknown> extends Error {
+declare class SuperLineError<Data = unknown> extends Error {
     /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
     readonly code: ErrorCode;
     /** Optional structured data attached to the error, delivered to the client. */
     readonly data?: Data;
     /**
-     * @param code - a {@link SocketErrorCode} or custom string.
+     * @param code - a {@link SuperLineErrorCode} or custom string.
      * @param message - human-readable message (defaults to `code`).
      * @param data - optional structured payload delivered to the client.
      */
@@ -36,8 +36,8 @@ interface Serializer {
 declare const jsonSerializer: Serializer;
 
 /**
- * Cross-node fan-out seam. Rooms, topics, and serverToServer all compile down to
- * channel pub/sub. A node subscribes to a channel only while it has a local member,
+ * Cross-node fan-out seam. Rooms, topics, and the cluster event bus all compile down
+ * to channel pub/sub. A node subscribes to a channel only while it has a local member,
  * and publishes always go through the adapter (the in-memory adapter loops back),
  * so a node delivers to its local members on receipt — one code path, no double-send.
  *
@@ -55,6 +55,75 @@ interface Adapter {
     onMessage(handler: (channel: string, payload: string | Uint8Array) => void): void;
     /** Optional teardown (e.g. close Redis connections). */
     close?(): void | Promise<void>;
+    /**
+     * Optional cluster-wide presence directory. Powers `srv.cluster.*` and
+     * `srv.isOnline`. The in-memory and Redis adapters implement it; cluster
+     * queries throw a clear error on an adapter that doesn't.
+     */
+    presence?: PresenceStore;
+}
+/** A serializable snapshot of a connection, shared cluster-wide via the {@link PresenceStore}. */
+interface ConnDescriptor {
+    /** The connection's server-assigned id. */
+    id: string;
+    /** The connection's role. */
+    role: string;
+    /** The node that holds this connection. */
+    nodeId: string;
+    /** The node's friendly name (defaults to a short slice of `nodeId`). */
+    nodeName: string;
+    /** When the connection was accepted (`Date.now()`). */
+    connectedAt: number;
+    /** The stable user key from the server's `identify` hook, if any. */
+    userId?: string;
+    /** Room memberships (topics and node-local `lastPongAt` are not included). */
+    rooms: string[];
+    /** Extra fields contributed by the server's `describeConn` hook. */
+    [extra: string]: unknown;
+}
+/** Per-node aggregate, returned by {@link PresenceStore.topology}. */
+interface NodeStat {
+    /** The node's id. */
+    nodeId: string;
+    /** The node's friendly name (defaults to a short slice of `nodeId`). */
+    nodeName: string;
+    /** Number of connections on the node. */
+    connections: number;
+    /** Number of distinct rooms with members on the node. */
+    rooms: number;
+    /** Whether the node is currently live (heartbeat fresh). */
+    alive: boolean;
+}
+/**
+ * Cluster-wide presence directory: a query/addressbook layer kept in the shared
+ * substrate (in-memory bus or Redis). Live message delivery does NOT read this —
+ * it exists only to answer `srv.cluster.*` / `srv.isOnline`.
+ */
+interface PresenceStore {
+    /** Record (or replace) a connection's descriptor. */
+    set(descriptor: ConnDescriptor): void | Promise<void>;
+    /** Remove a connection's descriptor. */
+    del(connId: string): void | Promise<void>;
+    /** Refresh this node's liveness (heartbeat). */
+    beat(nodeId: string): void | Promise<void>;
+    /** Remove all of a node's connections + liveness (graceful shutdown cleanup). */
+    clearNode(nodeId: string): void | Promise<void>;
+    /** Add a room to a connection's membership. */
+    addRoom(connId: string, room: string): void | Promise<void>;
+    /** Remove a room from a connection's membership. */
+    removeRoom(connId: string, room: string): void | Promise<void>;
+    /** All live connection descriptors across the cluster. */
+    list(): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** One connection's descriptor, if present. */
+    get(connId: string): (ConnDescriptor | undefined) | Promise<ConnDescriptor | undefined>;
+    /** Descriptors for a given user key. */
+    byUser(userId: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Descriptors that are members of `room`. */
+    roomMembers(room: string): ConnDescriptor[] | Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): number | Promise<number>;
+    /** Per-node aggregates. */
+    topology(): NodeStat[] | Promise<NodeStat[]>;
 }
 
 /** Any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…). */
@@ -80,25 +149,41 @@ interface ServerMessageDef {
     /** When `true`, clients opt in via `client.subscribe(...)` (a topic). Omit for a push event. */
     subscribe?: boolean;
 }
+/**
+ * A server→client request (request/response). The server sends `input`; the
+ * client's `implement` handler returns `output`. Lives in `serverToClient`
+ * alongside events and topics, distinguished by having `input`.
+ */
+interface ServerRequestDef {
+    /** Schema for the request payload the server sends. */
+    input: Schema;
+    /** Schema for the reply the client returns. */
+    output: Schema;
+}
+/** A `serverToClient` entry: a push event, a subscribable topic, or a server→client request. */
+type ServerEntry = ServerMessageDef | ServerRequestDef;
 /** The two directions within a `shared` or role block. */
 interface Directional {
     /** Requests this side may call (client→server). */
     clientToServer?: Record<string, RequestDef>;
-    /** Events/topics this side may receive (server→client). */
-    serverToClient?: Record<string, ServerMessageDef>;
+    /** Events, topics, and server→client requests this side may receive. */
+    serverToClient?: Record<string, ServerEntry>;
+}
+/** A role block: its directions plus an optional `data` schema typing `conn.data`. */
+interface RoleBlock extends Directional {
+    /** Schema for this role's mutable per-connection `conn.data` (server-side scratch state). */
+    data?: Schema;
 }
 /**
  * The single source of truth, imported by both server and client. Split by
  * **direction** and scoped by **role**: a `shared` base every role inherits,
- * plus one block per role. `serverToServer` is node↔node (not role-scoped).
+ * plus one block per role.
  */
 interface Contract {
     /** Surface common to every role (merged into each role's effective surface). */
     shared?: Directional;
     /** Per-role surfaces. A connection's role selects which one (plus `shared`) it sees. */
-    roles: Record<string, Directional>;
-    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
-    serverToServer?: Record<string, Schema>;
+    roles: Record<string, RoleBlock>;
 }
 /**
  * Define a contract. An identity function — `const` preserves literal keys and
@@ -118,7 +203,6 @@ interface Contract {
  *     user:  { clientToServer: { say:      { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
  *     agent: { clientToServer: { announce: { input: z.object({ text: z.string() }), output: z.object({ id: z.string() }) } } },
  *   },
- *   serverToServer: { rebalance: z.object({ shard: z.number() }) },
  * })
  * ```
  */
@@ -129,10 +213,12 @@ type CtsOf<D> = D extends {
     clientToServer: infer M extends Record<string, RequestDef>;
 } ? M : {};
 type StcOf<D> = D extends {
-    serverToClient: infer M extends Record<string, ServerMessageDef>;
+    serverToClient: infer M extends Record<string, ServerEntry>;
 } ? M : {};
 type EventsOf<M> = {
     [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? never : M[K] extends {
         subscribe: true;
     } ? never : K]: M[K];
 };
@@ -141,6 +227,11 @@ type TopicsOf<M> = {
         subscribe: true;
     } ? K : never]: M[K];
 };
+type ServerReqOf<M> = {
+    [K in keyof M as M[K] extends {
+        input: Schema;
+    } ? K : never]: M[K];
+};
 /** A role's effective request map: `shared` ∪ `roles[R]` client→server requests. */
 type Requests<C extends Contract, R extends RoleOf<C>> = CtsOf<C['shared']> & CtsOf<C['roles'][R]>;
 /** A role's effective server→client map (events and topics combined). */
@@ -159,8 +250,16 @@ type SharedEvents<C extends Contract> = EventsOf<StcOf<C['shared']>>;
 type SharedTopics<C extends Contract> = TopicsOf<StcOf<C['shared']>>;
 /** Subscribable topics in one role's block (published via `srv.forRole(r).publish`). */
 type RoleTopics<C extends Contract, R extends RoleOf<C>> = TopicsOf<StcOf<C['roles'][R]>>;
-/** The `serverToServer` map, or `{}` if the contract has none. */
-type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
+/** A role's effective server→client requests (`shared` ∪ `roles[R]`), answered by `client.implement`. */
+type ServerRequests<C extends Contract, R extends RoleOf<C>> = ServerReqOf<ServerMessages<C, R>>;
+/** Server→client requests in the `shared` block (the surface `srv.toConn(id).request` can call). */
+type SharedServerRequests<C extends Contract> = ServerReqOf<StcOf<C['shared']>>;
+/** The typed shape of `conn.data` for role `R` (its `data` schema, or an empty object). */
+type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
+    data: infer S extends Schema;
+} ? InferOut<S> : Record<string, never>;
+/** Union of every role's `conn.data` shape (used where the role isn't narrowed, e.g. shared handlers). */
+type AnyData<C extends Contract> = DataOf<C, RoleOf<C>>;
 /** The input type a client passes for a request (pre-validation). */
 type ClientInput<T> = T extends RequestDef ? InferIn<T['input']> : never;
 /** The input type a server handler receives for a request (post-validation). */
@@ -171,10 +270,6 @@ type Output<T> = T extends RequestDef ? InferOut<T['output']> : never;
 type EventData<T> = T extends ServerMessageDef ? InferOut<T['payload']> : never;
 /** The data a server sends for an event/topic (pre-validation). */
 type EmitData<T> = T extends ServerMessageDef ? InferIn<T['payload']> : never;
-/** The data a server sends for a serverToServer event. */
-type ServerEmit<T> = T extends Schema ? InferIn<T> : never;
-/** The data a server receives for a serverToServer event. */
-type ServerData<T> = T extends Schema ? InferOut<T> : never;
 /** Infer a schema's **input** type (what you pass into the validator). */
 type InferIn<S extends Schema> = StandardSchemaV1.InferInput<S>;
 /** Infer a schema's **output** type (the validated result). */
@@ -185,7 +280,7 @@ type InferOut<S extends Schema> = StandardSchemaV1.InferOutput<S>;
  * @param schema - the validator to run.
  * @param value - the untrusted value to validate.
  * @returns the parsed, typed value.
- * @throws {@link SocketError} with code `VALIDATION` if the value doesn't match.
+ * @throws {@link SuperLineError} with code `VALIDATION` if the value doesn't match.
  */
 declare function validate<S extends Schema>(schema: S, value: unknown): Promise<StandardSchemaV1.InferOutput<S>>;
 /**
@@ -194,10 +289,182 @@ declare function validate<S extends Schema>(schema: S, value: unknown): Promise<
  * @param schema - the validator to run.
  * @param value - the untrusted value to validate.
  * @returns the parsed, typed value.
- * @throws {@link SocketError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
+ * @throws {@link SuperLineError} with code `VALIDATION` on mismatch, or `INTERNAL` if the schema is async.
  */
 declare function validateSync<S extends Schema>(schema: S, value: unknown): StandardSchemaV1.InferOutput<S>;
 
+/** WS subprotocol the Control Center connects with; the server short-circuits auth for it. */
+declare const INSPECTOR_SUBPROTOCOL = "superline.inspector.v1";
+/** The reserved role minted for an inspector connection. */
+declare const INSPECTOR_ROLE = "inspector";
+/** How a contract message is used on the wire. */
+type MessageFlavor = 'request' | 'event' | 'topic' | 'serverRequest';
+/** One message in an {@link InspectedContract}. Schemas are best-effort JSON Schema, omitted when unavailable. */
+interface InspectedMessage {
+    /** The message name (its key in the contract). */
+    name: string;
+    /** How the message is used. */
+    flavor: MessageFlavor;
+    /** Best-effort JSON Schema of the request/server-request input. */
+    input?: unknown;
+    /** Best-effort JSON Schema of the request/server-request output. */
+    output?: unknown;
+    /** Best-effort JSON Schema of an event/topic payload. */
+    payload?: unknown;
+}
+/** The two directions of a `shared` or role block, flattened for display. */
+interface InspectedDirectional {
+    clientToServer: InspectedMessage[];
+    serverToClient: InspectedMessage[];
+}
+/** A serializable projection of a {@link Contract}'s structure — what `getContract` returns. */
+interface InspectedContract {
+    shared: InspectedDirectional;
+    roles: Record<string, InspectedDirectional>;
+}
+/** The connected node's local view — what `getNode` returns. */
+interface NodeView {
+    nodeId: string;
+    nodeName: string;
+    rooms: string[];
+    topics: string[];
+}
+/** A connection's detail — what `getConn` returns. ctx/data are node-local and best-effort safe-serialized. */
+interface ConnView {
+    descriptor: ConnDescriptor;
+    /** Safe-serialized auth ctx; present only when the conn is on the queried node. */
+    ctx?: unknown;
+    /** Safe-serialized `conn.data`; present only when the conn is on the queried node. */
+    data?: unknown;
+    /** Whether ctx/data could be read (false for conns on another node). */
+    ctxAvailable: boolean;
+}
+/** A failed response/reply, carried on `msg.response` / `msg.serverReply`. */
+interface MessageError {
+    code: string;
+    message: string;
+}
+/**
+ * A live event pushed on the `events` topic, fanned out cluster-wide. Lifecycle events
+ * (connect/disconnect/room/topic) are always emitted when inspector is on; `msg.*` events
+ * carry actual message traffic and are only emitted when inspector is on. Message payloads are
+ * safe-serialized and field-redacted (via the `inspector.redact` list) before they cross the bus.
+ */
+type InspectorEvent = {
+    type: 'connect';
+    descriptor: ConnDescriptor;
+} | {
+    type: 'disconnect';
+    connId: string;
+    nodeId: string;
+    userId?: string;
+} | {
+    type: 'room.add';
+    connId: string;
+    room: string;
+} | {
+    type: 'room.remove';
+    connId: string;
+    room: string;
+} | {
+    type: 'topic.sub';
+    connId: string;
+    topic: string;
+} | {
+    type: 'topic.unsub';
+    connId: string;
+    topic: string;
+} | {
+    type: 'msg.request';
+    connId: string;
+    role: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'msg.response';
+    connId: string;
+    name: string;
+    ok: boolean;
+    output?: unknown;
+    error?: MessageError;
+} | {
+    type: 'msg.event';
+    target: string;
+    name: string;
+    data: unknown;
+} | {
+    type: 'msg.broadcast';
+    room: string;
+    name: string;
+    data: unknown;
+} | {
+    type: 'msg.publish';
+    topic: string;
+    data: unknown;
+} | {
+    type: 'msg.serverRequest';
+    target: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'msg.serverReply';
+    target: string;
+    name: string;
+    ok: boolean;
+    output?: unknown;
+    error?: MessageError;
+};
+/**
+ * The fixed, library-owned contract describing the inspector surface. Identical for every
+ * super-line app, so it is NOT merged into the user's contract — inbound dispatch routes an
+ * inspector connection against this instead, which keeps the user's `RoleOf<C>` clean.
+ */
+declare const InspectorContract: {
+    readonly roles: {
+        readonly inspector: {
+            readonly clientToServer: {
+                readonly getContract: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<InspectedContract, InspectedContract>;
+                };
+                readonly getTopology: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<NodeStat[], NodeStat[]>;
+                };
+                readonly listConnections: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<ConnDescriptor[], ConnDescriptor[]>;
+                };
+                readonly getNode: {
+                    readonly input: StandardSchemaV1<void, void>;
+                    readonly output: StandardSchemaV1<NodeView, NodeView>;
+                };
+                readonly getConn: {
+                    readonly input: StandardSchemaV1<{
+                        id: string;
+                    }, {
+                        id: string;
+                    }>;
+                    readonly output: StandardSchemaV1<ConnView, ConnView>;
+                };
+            };
+            readonly serverToClient: {
+                readonly events: {
+                    readonly payload: StandardSchemaV1<InspectorEvent, InspectorEvent>;
+                    readonly subscribe: true;
+                };
+            };
+        };
+    };
+};
+/** A schema → JSON Schema converter (best-effort). Supplied by the server in slice 3. */
+type SchemaConverter = (schema: Schema) => unknown;
+/**
+ * Walk a contract and project its structure: roles × directions × message names × flavors.
+ * Pass `convert` to attach best-effort JSON Schema to each message; omit it for structure only.
+ */
+declare function classifyContract(contract: Contract, convert?: SchemaConverter): InspectedContract;
+
 /**
  * The wire protocol below is an implementation detail — you rarely touch frames
  * directly. It's exported for adapters, custom transports, and tooling.
@@ -219,7 +486,19 @@ interface UnsubFrame {
     t: 'unsub';
     c: string;
 }
-type ClientFrame = ReqFrame | SubFrame | UnsubFrame;
+interface SResFrame {
+    t: 'sres';
+    i: number;
+    d: unknown;
+}
+interface SErrFrame {
+    t: 'serr';
+    i: number;
+    code: string;
+    m: string;
+    d?: unknown;
+}
+type ClientFrame = ReqFrame | SubFrame | UnsubFrame | SResFrame | SErrFrame;
 interface ResFrame {
     t: 'res';
     i: number;
@@ -241,8 +520,15 @@ interface PubFrame {
     t: 'pub';
     c: string;
     d: unknown;
+    i?: string;
+}
+interface SReqFrame {
+    t: 'sreq';
+    i: number;
+    m: string;
+    d: unknown;
 }
-type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame;
+type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type ClientFrame, type ClientInput, type Contract, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type Output, PROTOCOL, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleOf, type RoleRequests, type RoleTopics, type Schema, type Serializer, type ServerData, type ServerEmit, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type SharedEvents, type SharedRequests, type SharedTopics, SocketError, type SocketErrorCode, type SubFrame, type Topics, type UnsubFrame, defineContract, jsonSerializer, validate, validateSync };
+export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type ConnView, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, INSPECTOR_ROLE, INSPECTOR_SUBPROTOCOL, type InferIn, type InferOut, type InspectedContract, type InspectedDirectional, type InspectedMessage, InspectorContract, type InspectorEvent, type MessageFlavor, type NodeStat, type NodeView, type Output, PROTOCOL, type PresenceStore, type PubFrame, type ReqFrame, type RequestDef, type Requests, type ResFrame, type RoleBlock, type RoleOf, type RoleRequests, type RoleTopics, type SErrFrame, type SReqFrame, type SResFrame, type Schema, type SchemaConverter, type Serializer, type ServerEntry, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, type SharedTopics, type SubFrame, SuperLineError, type SuperLineErrorCode, type Topics, type UnsubFrame, classifyContract, defineContract, jsonSerializer, validate, validateSync };

package/dist/index.js

@@ -1,17 +1,17 @@
 // src/errors.ts
-var SocketError = class extends Error {
+var SuperLineError = class extends Error {
   /** The typed error code (e.g. `'FORBIDDEN'`), available on the client. */
   code;
   /** Optional structured data attached to the error, delivered to the client. */
   data;
   /**
-   * @param code - a {@link SocketErrorCode} or custom string.
+   * @param code - a {@link SuperLineErrorCode} or custom string.
    * @param message - human-readable message (defaults to `code`).
    * @param data - optional structured payload delivered to the client.
    */
   constructor(code, message, data) {
     super(message ?? code);
-    this.name = "SocketError";
+    this.name = "SuperLineError";
     this.code = code;
     this.data = data;
   }
@@ -32,26 +32,99 @@ async function validate(schema, value) {
   let result = schema["~standard"].validate(value);
   if (result instanceof Promise) result = await result;
   if (result.issues) {
-    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+    throw new SuperLineError("VALIDATION", "Validation failed", result.issues);
   }
   return result.value;
 }
 function validateSync(schema, value) {
   const result = schema["~standard"].validate(value);
   if (result instanceof Promise) {
-    throw new SocketError("INTERNAL", "Async schema not supported for synchronous validation");
+    throw new SuperLineError("INTERNAL", "Async schema not supported for synchronous validation");
   }
   if (result.issues) {
-    throw new SocketError("VALIDATION", "Validation failed", result.issues);
+    throw new SuperLineError("VALIDATION", "Validation failed", result.issues);
   }
   return result.value;
 }
 
+// src/inspector.ts
+var INSPECTOR_SUBPROTOCOL = "superline.inspector.v1";
+var INSPECTOR_ROLE = "inspector";
+function s() {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "super-line-inspector",
+      validate: (value) => ({ value })
+    }
+  };
+}
+var InspectorContract = defineContract({
+  roles: {
+    inspector: {
+      clientToServer: {
+        getContract: { input: s(), output: s() },
+        getTopology: { input: s(), output: s() },
+        listConnections: { input: s(), output: s() },
+        getNode: { input: s(), output: s() },
+        getConn: { input: s(), output: s() }
+      },
+      serverToClient: {
+        events: { payload: s(), subscribe: true }
+      }
+    }
+  }
+});
+function withSchemas(msg, schemas, convert) {
+  if (!convert) return msg;
+  for (const [key, schema] of Object.entries(schemas)) {
+    const value = convert(schema);
+    if (value !== void 0) msg[key] = value;
+  }
+  return msg;
+}
+function classifyDirectional(d, convert) {
+  const clientToServer = [];
+  const serverToClient = [];
+  for (const [name, def] of Object.entries(d?.clientToServer ?? {})) {
+    clientToServer.push(
+      withSchemas({ name, flavor: "request" }, { input: def.input, output: def.output }, convert)
+    );
+  }
+  for (const [name, def] of Object.entries(d?.serverToClient ?? {})) {
+    if ("input" in def) {
+      serverToClient.push(
+        withSchemas({ name, flavor: "serverRequest" }, { input: def.input, output: def.output }, convert)
+      );
+    } else {
+      serverToClient.push(
+        withSchemas(
+          { name, flavor: def.subscribe === true ? "topic" : "event" },
+          { payload: def.payload },
+          convert
+        )
+      );
+    }
+  }
+  return { clientToServer, serverToClient };
+}
+function classifyContract(contract, convert) {
+  const roles = {};
+  for (const [role, block] of Object.entries(contract.roles)) {
+    roles[role] = classifyDirectional(block, convert);
+  }
+  return { shared: classifyDirectional(contract.shared, convert), roles };
+}
+
 // src/wire.ts
 var PROTOCOL = "superline.v1";
 export {
+  INSPECTOR_ROLE,
+  INSPECTOR_SUBPROTOCOL,
+  InspectorContract,
   PROTOCOL,
-  SocketError,
+  SuperLineError,
+  classifyContract,
   defineContract,
   jsonSerializer,
   validate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-line/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared contract, validation, wire protocol and errors for super-line.",
   "license": "MIT",