@super-line/core 0.2.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.
  *
@@ -70,6 +70,8 @@ interface ConnDescriptor {
     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. */
@@ -83,6 +85,8 @@ interface ConnDescriptor {
 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. */
@@ -173,15 +177,13 @@ interface RoleBlock extends Directional {
 /**
  * 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, RoleBlock>;
-    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
-    serverToServer?: Record<string, Schema>;
 }
 /**
  * Define a contract. An identity function — `const` preserves literal keys and
@@ -201,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() }) },
  * })
  * ```
  */
@@ -259,8 +260,6 @@ type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
 } ? 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 `serverToServer` map, or `{}` if the contract has none. */
-type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
 /** 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). */
@@ -271,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). */
@@ -285,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>>;
 /**
@@ -294,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.
@@ -353,6 +520,7 @@ interface PubFrame {
     t: 'pub';
     c: string;
     d: unknown;
+    i?: string;
 }
 interface SReqFrame {
     t: 'sreq';
@@ -363,4 +531,4 @@ interface SReqFrame {
 type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type NodeStat, 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 Serializer, type ServerData, type ServerEmit, type ServerEntry, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, 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.
  *
@@ -70,6 +70,8 @@ interface ConnDescriptor {
     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. */
@@ -83,6 +85,8 @@ interface ConnDescriptor {
 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. */
@@ -173,15 +177,13 @@ interface RoleBlock extends Directional {
 /**
  * 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, RoleBlock>;
-    /** Typed node-to-node event payloads, for {@link "@super-line/server"!}'s `emitServer`/`onServer`. */
-    serverToServer?: Record<string, Schema>;
 }
 /**
  * Define a contract. An identity function — `const` preserves literal keys and
@@ -201,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() }) },
  * })
  * ```
  */
@@ -259,8 +260,6 @@ type DataOf<C extends Contract, R extends RoleOf<C>> = C['roles'][R] extends {
 } ? 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 `serverToServer` map, or `{}` if the contract has none. */
-type ServerEvents<C extends Contract> = C['serverToServer'] extends Record<string, Schema> ? C['serverToServer'] : {};
 /** 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). */
@@ -271,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). */
@@ -285,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>>;
 /**
@@ -294,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.
@@ -353,6 +520,7 @@ interface PubFrame {
     t: 'pub';
     c: string;
     d: unknown;
+    i?: string;
 }
 interface SReqFrame {
     t: 'sreq';
@@ -363,4 +531,4 @@ interface SReqFrame {
 type ServerFrame = ResFrame | ErrFrame | EvtFrame | PubFrame | SReqFrame;
 type Frame = ClientFrame | ServerFrame;
 
-export { type Adapter, type AnyData, type ClientFrame, type ClientInput, type ConnDescriptor, type Contract, type DataOf, type Directional, type EmitData, type ErrFrame, type ErrorCode, type EventData, type Events, type EvtFrame, type Frame, type InferIn, type InferOut, type NodeStat, 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 Serializer, type ServerData, type ServerEmit, type ServerEntry, type ServerEvents, type ServerFrame, type ServerInput, type ServerMessageDef, type ServerMessages, type ServerRequestDef, type ServerRequests, type SharedEvents, type SharedRequests, type SharedServerRequests, 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.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared contract, validation, wire protocol and errors for super-line.",
   "license": "MIT",