@graphorin/protocol 0.6.0 → 0.7.0

package/dist/server-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-message.js","names":[],"sources":["../src/server-message.ts"],"sourcesContent":["/**\n * `ServerMessage` - discriminated union of every frame a Graphorin\n * server may push to a client. Three families share the channel:\n *\n *   1. **RPC responses** (`{ jsonrpc, id, result | error }`) -\n *      correlate with a previously-issued client request.\n *   2. **Typed push events** (`{ kind: 'event', subject, type,\n *      payload, eventId }`) - the streaming-first data plane;\n *      consumers ignore unknown `type` strings per the agent-event\n *      extensibility convention.\n *   3. **Asynchronous server frames** (`{ kind: 'lifecycle' | 'error'\n *      | 'pong' | 'subscribed' | 'unsubscribed' | 'replay-marker' }`)\n *      - server-initiated messages that do not correlate with a\n *      single client RPC id.\n *\n * Every frame carries the `v: '1'` literal so future revisions can\n * negotiate forward-compatible additions without a subprotocol bump.\n *\n * @packageDocumentation\n */\n\nimport { z } from 'zod';\n\nconst RpcId = z.union([z.string().min(1), z.number().int()]);\n\nconst RpcError = z\n  .object({\n    code: z.number().int(),\n    message: z.string().min(1),\n    data: z.unknown().optional(),\n  })\n  .strict();\n\nconst RpcSuccess = z\n  .object({\n    v: z.literal('1'),\n    jsonrpc: z.literal('2.0'),\n    id: RpcId,\n    result: z.unknown(),\n  })\n  .strict();\n\nconst RpcFailure = z\n  .object({\n    v: z.literal('1'),\n    jsonrpc: z.literal('2.0'),\n    id: RpcId,\n    error: RpcError,\n  })\n  .strict();\n\nconst SubscribedFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('subscribed'),\n    subscriptionId: z.string().min(1),\n    subject: z.string().min(1),\n    snapshotEventId: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst UnsubscribedFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('unsubscribed'),\n    subscriptionId: z.string().min(1),\n  })\n  .strict();\n\nconst EventFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('event'),\n    eventId: z.string().min(1),\n    subscriptionId: z.string().min(1),\n    subject: z.string().min(1),\n    type: z.string().min(1),\n    payload: z.unknown(),\n  })\n  .strict();\n\nconst LifecycleFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('lifecycle'),\n    subscriptionId: z.string().min(1),\n    status: z.enum(['running', 'paused', 'completed', 'aborted', 'failed']),\n    reason: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst ErrorFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('error'),\n    code: z.string().min(1),\n    message: z.string().min(1),\n    fatal: z.boolean().optional(),\n    subscriptionId: z.string().min(1).optional(),\n    data: z.unknown().optional(),\n  })\n  .strict();\n\nconst PongFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('pong'),\n    nonce: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst ReplayMarkerFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('replay-marker'),\n    subscriptionId: z.string().min(1),\n    eventId: z.string().min(1),\n    droppedCount: z.number().int().nonnegative().optional(),\n    note: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst KindedFrame = z.discriminatedUnion('kind', [\n  SubscribedFrame,\n  UnsubscribedFrame,\n  EventFrame,\n  LifecycleFrame,\n  ErrorFrame,\n  PongFrame,\n  ReplayMarkerFrame,\n]);\n\nconst RpcFrame = z.union([RpcSuccess, RpcFailure]);\n\n/**\n * Zod schema for every legal server → client frame. Validation runs\n * twice in the server pipeline: first when a route handler enqueues\n * the frame onto the dispatcher's send queue (so a malformed frame\n * never escapes the process), then again on the client side to\n * defend against protocol drift.\n *\n * @stable\n */\nexport const ServerMessageSchema = z.union([RpcFrame, KindedFrame]);\n\n/**\n * Inferred TypeScript union for the `ServerMessage` discriminator.\n *\n * @stable\n */\nexport type ServerMessage = z.infer<typeof ServerMessageSchema>;\n\n/**\n * Convenience type aliases for callers that want to reference an\n * individual variant without `z.infer<typeof X>`.\n *\n * @stable\n */\nexport type ServerEventFrame = z.infer<typeof EventFrame>;\n/** @stable */\nexport type ServerLifecycleFrame = z.infer<typeof LifecycleFrame>;\n/** @stable */\nexport type ServerErrorFrame = z.infer<typeof ErrorFrame>;\n/** @stable */\nexport type ServerSubscribedFrame = z.infer<typeof SubscribedFrame>;\n/** @stable */\nexport type ServerUnsubscribedFrame = z.infer<typeof UnsubscribedFrame>;\n/** @stable */\nexport type ServerPongFrame = z.infer<typeof PongFrame>;\n/** @stable */\nexport type ServerReplayMarkerFrame = z.infer<typeof ReplayMarkerFrame>;\n/** @stable */\nexport type ServerRpcSuccess = z.infer<typeof RpcSuccess>;\n/** @stable */\nexport type ServerRpcFailure = z.infer<typeof RpcFailure>;\n\n/**\n * Type guard helpers, one per discriminator. The narrow over the\n * `ServerMessage` union without forcing consumers to memorize the\n * exact field names.\n *\n * @stable\n */\nexport function isEventFrame(message: ServerMessage): message is ServerEventFrame {\n  return 'kind' in message && message.kind === 'event';\n}\n\n/** @stable */\nexport function isLifecycleFrame(message: ServerMessage): message is ServerLifecycleFrame {\n  return 'kind' in message && message.kind === 'lifecycle';\n}\n\n/** @stable */\nexport function isErrorFrame(message: ServerMessage): message is ServerErrorFrame {\n  return 'kind' in message && message.kind === 'error';\n}\n\n/** @stable */\nexport function isSubscribedFrame(message: ServerMessage): message is ServerSubscribedFrame {\n  return 'kind' in message && message.kind === 'subscribed';\n}\n\n/** @stable */\nexport function isUnsubscribedFrame(message: ServerMessage): message is ServerUnsubscribedFrame {\n  return 'kind' in message && message.kind === 'unsubscribed';\n}\n\n/** @stable */\nexport function isPongFrame(message: ServerMessage): message is ServerPongFrame {\n  return 'kind' in message && message.kind === 'pong';\n}\n\n/** @stable */\nexport function isReplayMarkerFrame(message: ServerMessage): message is ServerReplayMarkerFrame {\n  return 'kind' in message && message.kind === 'replay-marker';\n}\n\n/** @stable */\nexport function isRpcSuccess(message: ServerMessage): message is ServerRpcSuccess {\n  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'result' in message;\n}\n\n/** @stable */\nexport function isRpcFailure(message: ServerMessage): message is ServerRpcFailure {\n  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'error' in message;\n}\n\n/**\n * Stable JSON-RPC error code catalogue used by the server when\n * surfacing routine failures (per JSON-RPC 2.0 § 5.1 + Graphorin\n * extensions). Application-level errors use codes in the\n * implementation-defined range (`-32000` … `-32099`).\n *\n * @stable\n */\nexport const RPC_ERROR_CODES = Object.freeze({\n  PARSE_ERROR: -32700,\n  INVALID_REQUEST: -32600,\n  METHOD_NOT_FOUND: -32601,\n  INVALID_PARAMS: -32602,\n  INTERNAL_ERROR: -32603,\n  AUTH_REQUIRED: -32001,\n  AUTH_INVALID: -32002,\n  SCOPE_DENIED: -32003,\n  RATE_LIMITED: -32004,\n  PROTOCOL_VIOLATION: -32005,\n  RUN_NOT_FOUND: -32010,\n  SUBSCRIPTION_NOT_FOUND: -32011,\n} as const);\n"],"mappings":"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"}
+{"version":3,"file":"server-message.js","names":[],"sources":["../src/server-message.ts"],"sourcesContent":["/**\n * `ServerMessage` - discriminated union of every frame a Graphorin\n * server may push to a client. Three families share the channel:\n *\n *   1. **RPC responses** (`{ jsonrpc, id, result | error }`) -\n *      correlate with a previously-issued client request.\n *   2. **Typed push events** (`{ kind: 'event', subject, type,\n *      payload, eventId }`) - the streaming-first data plane;\n *      consumers ignore unknown `type` strings per the agent-event\n *      extensibility convention.\n *   3. **Asynchronous server frames** (`{ kind: 'lifecycle' | 'error'\n *      | 'pong' | 'subscribed' | 'unsubscribed' | 'replay-marker' }`)\n *      - server-initiated messages that do not correlate with a\n *      single client RPC id.\n *\n * Versioning contract (W-109, honest edition): the frame ENVELOPE -\n * the set of `kind`s, the fields of the control frames, and the\n * `v: '1'` literal - is validated strictly (`.strict()`, literal `v`)\n * on BOTH server and client, and evolves only in lockstep with both\n * sides shipping together: there is NO negotiation, and a frame with\n * `v: '2'` is rejected outright. That is the deployment model of the\n * 0.x line. The additive extension points are deliberate and inside\n * the envelope: the `type` string + `payload: z.unknown()` of event\n * frames (consumers ignore unknown `type`s per the agent-event\n * convention), `result: z.unknown()` of RPC responses, and the\n * `capabilities` record of the `initialize` result (which today the\n * shipped client does not consume). If additive envelope evolution is\n * ever promised publicly, that is a separate negotiation feature -\n * do not loosen `.strict()` for it piecemeal.\n *\n * @packageDocumentation\n */\n\nimport { z } from 'zod';\n\nconst RpcId = z.union([z.string().min(1), z.number().int()]);\n\nconst RpcError = z\n  .object({\n    code: z.number().int(),\n    message: z.string().min(1),\n    data: z.unknown().optional(),\n  })\n  .strict();\n\nconst RpcSuccess = z\n  .object({\n    v: z.literal('1'),\n    jsonrpc: z.literal('2.0'),\n    id: RpcId,\n    result: z.unknown(),\n  })\n  .strict();\n\nconst RpcFailure = z\n  .object({\n    v: z.literal('1'),\n    jsonrpc: z.literal('2.0'),\n    id: RpcId,\n    error: RpcError,\n  })\n  .strict();\n\nconst SubscribedFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('subscribed'),\n    subscriptionId: z.string().min(1),\n    subject: z.string().min(1),\n    snapshotEventId: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst UnsubscribedFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('unsubscribed'),\n    subscriptionId: z.string().min(1),\n  })\n  .strict();\n\n// The runtime schema keeps `payload` opaque so this package stays\n// zod-only (no `@graphorin/core` dependency, not even type-only - it\n// would force a resolvable dependency for the d.ts). For agent-run\n// subjects the actual payload shape is the JSON-safe `WireAgentEvent`\n// union documented in `@graphorin/core` (decode with\n// `fromWireAgentEvent`); the cross-package round-trip is pinned by a\n// gate test in core.\nconst EventFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('event'),\n    eventId: z.string().min(1),\n    subscriptionId: z.string().min(1),\n    subject: z.string().min(1),\n    type: z.string().min(1),\n    payload: z.unknown(),\n  })\n  .strict();\n\nconst LifecycleFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('lifecycle'),\n    subscriptionId: z.string().min(1),\n    status: z.enum(['running', 'paused', 'completed', 'aborted', 'failed']),\n    reason: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst ErrorFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('error'),\n    code: z.string().min(1),\n    message: z.string().min(1),\n    fatal: z.boolean().optional(),\n    subscriptionId: z.string().min(1).optional(),\n    data: z.unknown().optional(),\n  })\n  .strict();\n\nconst PongFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('pong'),\n    nonce: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst ReplayMarkerFrame = z\n  .object({\n    v: z.literal('1'),\n    kind: z.literal('replay-marker'),\n    subscriptionId: z.string().min(1),\n    eventId: z.string().min(1),\n    droppedCount: z.number().int().nonnegative().optional(),\n    note: z.string().min(1).optional(),\n  })\n  .strict();\n\nconst KindedFrame = z.discriminatedUnion('kind', [\n  SubscribedFrame,\n  UnsubscribedFrame,\n  EventFrame,\n  LifecycleFrame,\n  ErrorFrame,\n  PongFrame,\n  ReplayMarkerFrame,\n]);\n\nconst RpcFrame = z.union([RpcSuccess, RpcFailure]);\n\n/**\n * Zod schema for every legal server → client frame. Validation runs\n * twice in the server pipeline: first when a route handler enqueues\n * the frame onto the dispatcher's send queue (so a malformed frame\n * never escapes the process), then again on the client side to\n * defend against protocol drift.\n *\n * @stable\n */\nexport const ServerMessageSchema = z.union([RpcFrame, KindedFrame]);\n\n/**\n * Inferred TypeScript union for the `ServerMessage` discriminator.\n *\n * @stable\n */\nexport type ServerMessage = z.infer<typeof ServerMessageSchema>;\n\n/**\n * Convenience type aliases for callers that want to reference an\n * individual variant without `z.infer<typeof X>`.\n *\n * @stable\n */\nexport type ServerEventFrame = z.infer<typeof EventFrame>;\n/** @stable */\nexport type ServerLifecycleFrame = z.infer<typeof LifecycleFrame>;\n/** @stable */\nexport type ServerErrorFrame = z.infer<typeof ErrorFrame>;\n/** @stable */\nexport type ServerSubscribedFrame = z.infer<typeof SubscribedFrame>;\n/** @stable */\nexport type ServerUnsubscribedFrame = z.infer<typeof UnsubscribedFrame>;\n/** @stable */\nexport type ServerPongFrame = z.infer<typeof PongFrame>;\n/** @stable */\nexport type ServerReplayMarkerFrame = z.infer<typeof ReplayMarkerFrame>;\n/** @stable */\nexport type ServerRpcSuccess = z.infer<typeof RpcSuccess>;\n/** @stable */\nexport type ServerRpcFailure = z.infer<typeof RpcFailure>;\n\n/**\n * Type guard helpers, one per discriminator. The narrow over the\n * `ServerMessage` union without forcing consumers to memorize the\n * exact field names.\n *\n * @stable\n */\nexport function isEventFrame(message: ServerMessage): message is ServerEventFrame {\n  return 'kind' in message && message.kind === 'event';\n}\n\n/** @stable */\nexport function isLifecycleFrame(message: ServerMessage): message is ServerLifecycleFrame {\n  return 'kind' in message && message.kind === 'lifecycle';\n}\n\n/** @stable */\nexport function isErrorFrame(message: ServerMessage): message is ServerErrorFrame {\n  return 'kind' in message && message.kind === 'error';\n}\n\n/** @stable */\nexport function isSubscribedFrame(message: ServerMessage): message is ServerSubscribedFrame {\n  return 'kind' in message && message.kind === 'subscribed';\n}\n\n/** @stable */\nexport function isUnsubscribedFrame(message: ServerMessage): message is ServerUnsubscribedFrame {\n  return 'kind' in message && message.kind === 'unsubscribed';\n}\n\n/** @stable */\nexport function isPongFrame(message: ServerMessage): message is ServerPongFrame {\n  return 'kind' in message && message.kind === 'pong';\n}\n\n/** @stable */\nexport function isReplayMarkerFrame(message: ServerMessage): message is ServerReplayMarkerFrame {\n  return 'kind' in message && message.kind === 'replay-marker';\n}\n\n/** @stable */\nexport function isRpcSuccess(message: ServerMessage): message is ServerRpcSuccess {\n  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'result' in message;\n}\n\n/** @stable */\nexport function isRpcFailure(message: ServerMessage): message is ServerRpcFailure {\n  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'error' in message;\n}\n\n/**\n * Stable JSON-RPC error code catalogue used by the server when\n * surfacing routine failures (per JSON-RPC 2.0 § 5.1 + Graphorin\n * extensions). Application-level errors use codes in the\n * implementation-defined range (`-32000` … `-32099`).\n *\n * @stable\n */\nexport const RPC_ERROR_CODES = Object.freeze({\n  PARSE_ERROR: -32700,\n  INVALID_REQUEST: -32600,\n  METHOD_NOT_FOUND: -32601,\n  INVALID_PARAMS: -32602,\n  INTERNAL_ERROR: -32603,\n  AUTH_REQUIRED: -32001,\n  AUTH_INVALID: -32002,\n  SCOPE_DENIED: -32003,\n  RATE_LIMITED: -32004,\n  PROTOCOL_VIOLATION: -32005,\n  RUN_NOT_FOUND: -32010,\n  SUBSCRIPTION_NOT_FOUND: -32011,\n} as const);\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/protocol",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Wire protocol contract for the Graphorin framework: Zod schemas + TypeScript types for the WebSocket subprotocol `graphorin.protocol.v1`. Defines the `ClientMessage` and `ServerMessage` discriminated unions, the JSON-RPC-shaped control channel (`initialize` / `subscription.subscribe` / `subscription.unsubscribe` / `run.cancel` / `ping`), the typed event push frames (`{ kind: 'event', subject, type, payload, eventId }`), the asynchronous server-initiated error frames (`{ kind: 'error', code, message }`), the subprotocol negotiation helpers, and the close-code taxonomy (4001 auth.required, 4002 auth.invalid, 4003 auth.revoked, 4004 auth.scope_denied, 4005 rate.limited, 4006 flow.throttled, 4007 server.shutdown, 4008 protocol.violation). Browser-friendly: zero Node-only dependencies; the only runtime dependency is `zod`. Created and maintained by Oleksiy Stepurenko.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -27,7 +27,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -36,28 +36,29 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./client-message": {
       "types": "./dist/client-message.d.ts",
-      "import": "./dist/client-message.js"
+      "default": "./dist/client-message.js"
     },
     "./server-message": {
       "types": "./dist/server-message.d.ts",
-      "import": "./dist/server-message.js"
+      "default": "./dist/server-message.js"
     },
     "./subprotocol": {
       "types": "./dist/subprotocol.d.ts",
-      "import": "./dist/subprotocol.js"
+      "default": "./dist/subprotocol.js"
     },
     "./close-codes": {
       "types": "./dist/close-codes.d.ts",
-      "import": "./dist/close-codes.js"
+      "default": "./dist/close-codes.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/client-message.ts

@@ -0,0 +1,200 @@
+/**
+ * `ClientMessage` - discriminated union of every frame a Graphorin
+ * WebSocket client may send to the server. The wire is hybrid: the
+ * control plane uses JSON-RPC-shaped requests / notifications; the
+ * data plane uses typed push events emitted exclusively by the server
+ * (see `./server-message.ts`).
+ *
+ * Every frame carries the `v: '1'` literal so future revisions can
+ * negotiate forward-compatible additions without a subprotocol bump.
+ * The matching subprotocol identifier is `graphorin.protocol.v1`
+ * (see `./subprotocol.ts`).
+ *
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+const RpcId = z.union([z.string().min(1), z.number().int()]);
+
+const InitializeParams = z
+  .object({
+    clientInfo: z
+      .object({
+        name: z.string().min(1),
+        version: z.string().min(1),
+      })
+      .strict(),
+    capabilities: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+const SubscribeParams = z
+  .object({
+    subject: z.string().min(1),
+    // IP-21: `sinceEventId` is the resumption cursor. `lastSequenceId` was a
+    // dead wire field - the client never set it and the server never read it.
+    sinceEventId: z.string().min(1).optional(),
+  })
+  .strict();
+
+const UnsubscribeParams = z
+  .object({
+    subscriptionId: z.string().min(1),
+  })
+  .strict();
+
+const RunCancelParams = z
+  .object({
+    runId: z.string().min(1),
+    reason: z.string().min(1).optional(),
+    drain: z.boolean().optional(),
+    onPendingApprovals: z.enum(['deny', 'preserve']).optional(),
+  })
+  .strict();
+
+const PingParams = z
+  .object({
+    nonce: z.string().min(1).optional(),
+  })
+  .strict()
+  .optional();
+
+const InitializeRequest = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    method: z.literal('initialize'),
+    params: InitializeParams,
+  })
+  .strict();
+
+const SubscribeRequest = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    method: z.literal('subscription.subscribe'),
+    params: SubscribeParams,
+  })
+  .strict();
+
+const UnsubscribeRequest = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    method: z.literal('subscription.unsubscribe'),
+    params: UnsubscribeParams,
+  })
+  .strict();
+
+const RunCancelRequest = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    method: z.literal('run.cancel'),
+    params: RunCancelParams,
+  })
+  .strict();
+
+const PingRequest = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    method: z.literal('ping'),
+    params: PingParams,
+  })
+  .strict();
+
+const CancelledNotification = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    method: z.literal('notifications/cancelled'),
+    params: z.object({ requestId: z.string().min(1) }).strict(),
+  })
+  .strict();
+
+/**
+ * Zod schema for every legal client → server frame. Use
+ * {@link ClientMessageSchema}.safeParse() inside the server upgrade
+ * handler before dispatching to the corresponding subscription /
+ * cancel / ping handler.
+ *
+ * @stable
+ */
+export const ClientMessageSchema = z.discriminatedUnion('method', [
+  InitializeRequest,
+  SubscribeRequest,
+  UnsubscribeRequest,
+  RunCancelRequest,
+  PingRequest,
+  CancelledNotification,
+]);
+
+/**
+ * Inferred TypeScript union for the `ClientMessage` discriminator. A
+ * value satisfying this type round-trips through
+ * {@link ClientMessageSchema} without throwing.
+ *
+ * @stable
+ */
+export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+
+/**
+ * Convenience type for the JSON-RPC `id` slot. Matches the Graphorin
+ * subset (string + integer; no `null`, no float).
+ *
+ * @stable
+ */
+export type ClientMessageId = z.infer<typeof RpcId>;
+
+/**
+ * Type guard helpers - one per `method` literal - so consumers can
+ * narrow the `ClientMessage` union without re-stringifying the
+ * discriminator.
+ *
+ * @stable
+ */
+export function isInitializeRequest(
+  message: ClientMessage,
+): message is z.infer<typeof InitializeRequest> {
+  return message.method === 'initialize';
+}
+
+/** @stable */
+export function isSubscribeRequest(
+  message: ClientMessage,
+): message is z.infer<typeof SubscribeRequest> {
+  return message.method === 'subscription.subscribe';
+}
+
+/** @stable */
+export function isUnsubscribeRequest(
+  message: ClientMessage,
+): message is z.infer<typeof UnsubscribeRequest> {
+  return message.method === 'subscription.unsubscribe';
+}
+
+/** @stable */
+export function isRunCancelRequest(
+  message: ClientMessage,
+): message is z.infer<typeof RunCancelRequest> {
+  return message.method === 'run.cancel';
+}
+
+/** @stable */
+export function isPingRequest(message: ClientMessage): message is z.infer<typeof PingRequest> {
+  return message.method === 'ping';
+}
+
+/** @stable */
+export function isCancelledNotification(
+  message: ClientMessage,
+): message is z.infer<typeof CancelledNotification> {
+  return message.method === 'notifications/cancelled';
+}

package/src/close-codes.ts

@@ -0,0 +1,67 @@
+/**
+ * Custom WebSocket close-code taxonomy used by `@graphorin/server`
+ * and `@graphorin/client`. The numeric values live in the 4xxx
+ * application-private range per RFC 6455 § 7.4.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Discriminator for every Graphorin-defined close code. The
+ * matching numeric value is exposed via {@link CLOSE_CODE_VALUES}.
+ *
+ * @stable
+ */
+export type GraphorinCloseReason =
+  | 'auth.required'
+  | 'auth.invalid'
+  | 'auth.revoked'
+  | 'auth.scope_denied'
+  | 'rate.limited'
+  | 'flow.throttled'
+  | 'server.shutdown'
+  | 'protocol.violation';
+
+/**
+ * Numeric close-code constants. The pair `(value, reason)` round-trips
+ * via {@link closeCodeReason} / {@link closeCodeFor}.
+ *
+ * @stable
+ */
+export const CLOSE_CODE_VALUES = Object.freeze({
+  'auth.required': 4001,
+  'auth.invalid': 4002,
+  'auth.revoked': 4003,
+  'auth.scope_denied': 4004,
+  'rate.limited': 4005,
+  'flow.throttled': 4006,
+  'server.shutdown': 4007,
+  'protocol.violation': 4008,
+} as const satisfies Record<GraphorinCloseReason, number>);
+
+/**
+ * Return the numeric close code for a Graphorin reason discriminator.
+ *
+ * @stable
+ */
+export function closeCodeFor(reason: GraphorinCloseReason): number {
+  return CLOSE_CODE_VALUES[reason];
+}
+
+const REVERSE_LOOKUP: ReadonlyMap<number, GraphorinCloseReason> = new Map(
+  (Object.entries(CLOSE_CODE_VALUES) as ReadonlyArray<[GraphorinCloseReason, number]>).map(
+    ([reason, code]) => [code, reason],
+  ),
+);
+
+/**
+ * Resolve a numeric close code back to its Graphorin reason
+ * discriminator. Returns `undefined` for codes outside the
+ * Graphorin range so callers can still surface the raw RFC 6455
+ * reason for unrelated codes.
+ *
+ * @stable
+ */
+export function closeCodeReason(code: number): GraphorinCloseReason | undefined {
+  return REVERSE_LOOKUP.get(code);
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * `@graphorin/protocol` - wire-format contract for the Graphorin
+ * WebSocket subprotocol.
+ *
+ * The package is the **single source of truth** for the shape of
+ * every frame exchanged over `wss://.../v1/ws`. Both
+ * `@graphorin/server` and `@graphorin/client` import their schemas
+ * from here so the two implementations cannot drift.
+ *
+ * Browser-friendly: the only runtime dependency is
+ * [`zod`](https://zod.dev). No Node-only imports, no DOM-only
+ * imports.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export * from './client-message.js';
+export * from './close-codes.js';
+export * from './server-message.js';
+export * from './subprotocol.js';

package/src/server-message.ts

@@ -0,0 +1,268 @@
+/**
+ * `ServerMessage` - discriminated union of every frame a Graphorin
+ * server may push to a client. Three families share the channel:
+ *
+ *   1. **RPC responses** (`{ jsonrpc, id, result | error }`) -
+ *      correlate with a previously-issued client request.
+ *   2. **Typed push events** (`{ kind: 'event', subject, type,
+ *      payload, eventId }`) - the streaming-first data plane;
+ *      consumers ignore unknown `type` strings per the agent-event
+ *      extensibility convention.
+ *   3. **Asynchronous server frames** (`{ kind: 'lifecycle' | 'error'
+ *      | 'pong' | 'subscribed' | 'unsubscribed' | 'replay-marker' }`)
+ *      - server-initiated messages that do not correlate with a
+ *      single client RPC id.
+ *
+ * Versioning contract (W-109, honest edition): the frame ENVELOPE -
+ * the set of `kind`s, the fields of the control frames, and the
+ * `v: '1'` literal - is validated strictly (`.strict()`, literal `v`)
+ * on BOTH server and client, and evolves only in lockstep with both
+ * sides shipping together: there is NO negotiation, and a frame with
+ * `v: '2'` is rejected outright. That is the deployment model of the
+ * 0.x line. The additive extension points are deliberate and inside
+ * the envelope: the `type` string + `payload: z.unknown()` of event
+ * frames (consumers ignore unknown `type`s per the agent-event
+ * convention), `result: z.unknown()` of RPC responses, and the
+ * `capabilities` record of the `initialize` result (which today the
+ * shipped client does not consume). If additive envelope evolution is
+ * ever promised publicly, that is a separate negotiation feature -
+ * do not loosen `.strict()` for it piecemeal.
+ *
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+const RpcId = z.union([z.string().min(1), z.number().int()]);
+
+const RpcError = z
+  .object({
+    code: z.number().int(),
+    message: z.string().min(1),
+    data: z.unknown().optional(),
+  })
+  .strict();
+
+const RpcSuccess = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    result: z.unknown(),
+  })
+  .strict();
+
+const RpcFailure = z
+  .object({
+    v: z.literal('1'),
+    jsonrpc: z.literal('2.0'),
+    id: RpcId,
+    error: RpcError,
+  })
+  .strict();
+
+const SubscribedFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('subscribed'),
+    subscriptionId: z.string().min(1),
+    subject: z.string().min(1),
+    snapshotEventId: z.string().min(1).optional(),
+  })
+  .strict();
+
+const UnsubscribedFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('unsubscribed'),
+    subscriptionId: z.string().min(1),
+  })
+  .strict();
+
+// The runtime schema keeps `payload` opaque so this package stays
+// zod-only (no `@graphorin/core` dependency, not even type-only - it
+// would force a resolvable dependency for the d.ts). For agent-run
+// subjects the actual payload shape is the JSON-safe `WireAgentEvent`
+// union documented in `@graphorin/core` (decode with
+// `fromWireAgentEvent`); the cross-package round-trip is pinned by a
+// gate test in core.
+const EventFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('event'),
+    eventId: z.string().min(1),
+    subscriptionId: z.string().min(1),
+    subject: z.string().min(1),
+    type: z.string().min(1),
+    payload: z.unknown(),
+  })
+  .strict();
+
+const LifecycleFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('lifecycle'),
+    subscriptionId: z.string().min(1),
+    status: z.enum(['running', 'paused', 'completed', 'aborted', 'failed']),
+    reason: z.string().min(1).optional(),
+  })
+  .strict();
+
+const ErrorFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('error'),
+    code: z.string().min(1),
+    message: z.string().min(1),
+    fatal: z.boolean().optional(),
+    subscriptionId: z.string().min(1).optional(),
+    data: z.unknown().optional(),
+  })
+  .strict();
+
+const PongFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('pong'),
+    nonce: z.string().min(1).optional(),
+  })
+  .strict();
+
+const ReplayMarkerFrame = z
+  .object({
+    v: z.literal('1'),
+    kind: z.literal('replay-marker'),
+    subscriptionId: z.string().min(1),
+    eventId: z.string().min(1),
+    droppedCount: z.number().int().nonnegative().optional(),
+    note: z.string().min(1).optional(),
+  })
+  .strict();
+
+const KindedFrame = z.discriminatedUnion('kind', [
+  SubscribedFrame,
+  UnsubscribedFrame,
+  EventFrame,
+  LifecycleFrame,
+  ErrorFrame,
+  PongFrame,
+  ReplayMarkerFrame,
+]);
+
+const RpcFrame = z.union([RpcSuccess, RpcFailure]);
+
+/**
+ * Zod schema for every legal server → client frame. Validation runs
+ * twice in the server pipeline: first when a route handler enqueues
+ * the frame onto the dispatcher's send queue (so a malformed frame
+ * never escapes the process), then again on the client side to
+ * defend against protocol drift.
+ *
+ * @stable
+ */
+export const ServerMessageSchema = z.union([RpcFrame, KindedFrame]);
+
+/**
+ * Inferred TypeScript union for the `ServerMessage` discriminator.
+ *
+ * @stable
+ */
+export type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+/**
+ * Convenience type aliases for callers that want to reference an
+ * individual variant without `z.infer<typeof X>`.
+ *
+ * @stable
+ */
+export type ServerEventFrame = z.infer<typeof EventFrame>;
+/** @stable */
+export type ServerLifecycleFrame = z.infer<typeof LifecycleFrame>;
+/** @stable */
+export type ServerErrorFrame = z.infer<typeof ErrorFrame>;
+/** @stable */
+export type ServerSubscribedFrame = z.infer<typeof SubscribedFrame>;
+/** @stable */
+export type ServerUnsubscribedFrame = z.infer<typeof UnsubscribedFrame>;
+/** @stable */
+export type ServerPongFrame = z.infer<typeof PongFrame>;
+/** @stable */
+export type ServerReplayMarkerFrame = z.infer<typeof ReplayMarkerFrame>;
+/** @stable */
+export type ServerRpcSuccess = z.infer<typeof RpcSuccess>;
+/** @stable */
+export type ServerRpcFailure = z.infer<typeof RpcFailure>;
+
+/**
+ * Type guard helpers, one per discriminator. The narrow over the
+ * `ServerMessage` union without forcing consumers to memorize the
+ * exact field names.
+ *
+ * @stable
+ */
+export function isEventFrame(message: ServerMessage): message is ServerEventFrame {
+  return 'kind' in message && message.kind === 'event';
+}
+
+/** @stable */
+export function isLifecycleFrame(message: ServerMessage): message is ServerLifecycleFrame {
+  return 'kind' in message && message.kind === 'lifecycle';
+}
+
+/** @stable */
+export function isErrorFrame(message: ServerMessage): message is ServerErrorFrame {
+  return 'kind' in message && message.kind === 'error';
+}
+
+/** @stable */
+export function isSubscribedFrame(message: ServerMessage): message is ServerSubscribedFrame {
+  return 'kind' in message && message.kind === 'subscribed';
+}
+
+/** @stable */
+export function isUnsubscribedFrame(message: ServerMessage): message is ServerUnsubscribedFrame {
+  return 'kind' in message && message.kind === 'unsubscribed';
+}
+
+/** @stable */
+export function isPongFrame(message: ServerMessage): message is ServerPongFrame {
+  return 'kind' in message && message.kind === 'pong';
+}
+
+/** @stable */
+export function isReplayMarkerFrame(message: ServerMessage): message is ServerReplayMarkerFrame {
+  return 'kind' in message && message.kind === 'replay-marker';
+}
+
+/** @stable */
+export function isRpcSuccess(message: ServerMessage): message is ServerRpcSuccess {
+  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'result' in message;
+}
+
+/** @stable */
+export function isRpcFailure(message: ServerMessage): message is ServerRpcFailure {
+  return 'jsonrpc' in message && message.jsonrpc === '2.0' && 'error' in message;
+}
+
+/**
+ * Stable JSON-RPC error code catalogue used by the server when
+ * surfacing routine failures (per JSON-RPC 2.0 § 5.1 + Graphorin
+ * extensions). Application-level errors use codes in the
+ * implementation-defined range (`-32000` … `-32099`).
+ *
+ * @stable
+ */
+export const RPC_ERROR_CODES = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  AUTH_REQUIRED: -32001,
+  AUTH_INVALID: -32002,
+  SCOPE_DENIED: -32003,
+  RATE_LIMITED: -32004,
+  PROTOCOL_VIOLATION: -32005,
+  RUN_NOT_FOUND: -32010,
+  SUBSCRIPTION_NOT_FOUND: -32011,
+} as const);