@graphorin/protocol 0.5.0

package/dist/server-message.d.ts

@@ -0,0 +1,459 @@
+import { z } from "zod";
+
+//#region src/server-message.d.ts
+
+declare const RpcSuccess: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  jsonrpc: z.ZodLiteral<"2.0">;
+  id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+  result: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+}, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+}>;
+declare const RpcFailure: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  jsonrpc: z.ZodLiteral<"2.0">;
+  id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+  error: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+  }, "strict", z.ZodTypeAny, {
+    code: number;
+    message: string;
+    data?: unknown;
+  }, {
+    code: number;
+    message: string;
+    data?: unknown;
+  }>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}>;
+declare const SubscribedFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"subscribed">;
+  subscriptionId: z.ZodString;
+  subject: z.ZodString;
+  snapshotEventId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subject: string;
+  subscriptionId: string;
+  kind: "subscribed";
+  snapshotEventId?: string | undefined;
+}, {
+  v: "1";
+  subject: string;
+  subscriptionId: string;
+  kind: "subscribed";
+  snapshotEventId?: string | undefined;
+}>;
+declare const UnsubscribedFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"unsubscribed">;
+  subscriptionId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subscriptionId: string;
+  kind: "unsubscribed";
+}, {
+  v: "1";
+  subscriptionId: string;
+  kind: "unsubscribed";
+}>;
+declare const EventFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"event">;
+  eventId: z.ZodString;
+  subscriptionId: z.ZodString;
+  subject: z.ZodString;
+  type: z.ZodString;
+  payload: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  type: string;
+  subject: string;
+  subscriptionId: string;
+  kind: "event";
+  eventId: string;
+  payload?: unknown;
+}, {
+  v: "1";
+  type: string;
+  subject: string;
+  subscriptionId: string;
+  kind: "event";
+  eventId: string;
+  payload?: unknown;
+}>;
+declare const LifecycleFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"lifecycle">;
+  subscriptionId: z.ZodString;
+  status: z.ZodEnum<["running", "paused", "completed", "aborted", "failed"]>;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  status: "aborted" | "running" | "paused" | "completed" | "failed";
+  subscriptionId: string;
+  kind: "lifecycle";
+  reason?: string | undefined;
+}, {
+  v: "1";
+  status: "aborted" | "running" | "paused" | "completed" | "failed";
+  subscriptionId: string;
+  kind: "lifecycle";
+  reason?: string | undefined;
+}>;
+declare const ErrorFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"error">;
+  code: z.ZodString;
+  message: z.ZodString;
+  fatal: z.ZodOptional<z.ZodBoolean>;
+  subscriptionId: z.ZodOptional<z.ZodString>;
+  data: z.ZodOptional<z.ZodUnknown>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  code: string;
+  message: string;
+  kind: "error";
+  subscriptionId?: string | undefined;
+  data?: unknown;
+  fatal?: boolean | undefined;
+}, {
+  v: "1";
+  code: string;
+  message: string;
+  kind: "error";
+  subscriptionId?: string | undefined;
+  data?: unknown;
+  fatal?: boolean | undefined;
+}>;
+declare const PongFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"pong">;
+  nonce: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  kind: "pong";
+  nonce?: string | undefined;
+}, {
+  v: "1";
+  kind: "pong";
+  nonce?: string | undefined;
+}>;
+declare const ReplayMarkerFrame: z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"replay-marker">;
+  subscriptionId: z.ZodString;
+  eventId: z.ZodString;
+  droppedCount: z.ZodOptional<z.ZodNumber>;
+  note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subscriptionId: string;
+  kind: "replay-marker";
+  eventId: string;
+  droppedCount?: number | undefined;
+  note?: string | undefined;
+}, {
+  v: "1";
+  subscriptionId: string;
+  kind: "replay-marker";
+  eventId: string;
+  droppedCount?: number | undefined;
+  note?: string | undefined;
+}>;
+/**
+ * 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
+ */
+declare const ServerMessageSchema: z.ZodUnion<[z.ZodUnion<[z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  jsonrpc: z.ZodLiteral<"2.0">;
+  id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+  result: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+}, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  jsonrpc: z.ZodLiteral<"2.0">;
+  id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+  error: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+  }, "strict", z.ZodTypeAny, {
+    code: number;
+    message: string;
+    data?: unknown;
+  }, {
+    code: number;
+    message: string;
+    data?: unknown;
+  }>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}, {
+  v: "1";
+  jsonrpc: "2.0";
+  id: string | number;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}>]>, z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"subscribed">;
+  subscriptionId: z.ZodString;
+  subject: z.ZodString;
+  snapshotEventId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subject: string;
+  subscriptionId: string;
+  kind: "subscribed";
+  snapshotEventId?: string | undefined;
+}, {
+  v: "1";
+  subject: string;
+  subscriptionId: string;
+  kind: "subscribed";
+  snapshotEventId?: string | undefined;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"unsubscribed">;
+  subscriptionId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subscriptionId: string;
+  kind: "unsubscribed";
+}, {
+  v: "1";
+  subscriptionId: string;
+  kind: "unsubscribed";
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"event">;
+  eventId: z.ZodString;
+  subscriptionId: z.ZodString;
+  subject: z.ZodString;
+  type: z.ZodString;
+  payload: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  type: string;
+  subject: string;
+  subscriptionId: string;
+  kind: "event";
+  eventId: string;
+  payload?: unknown;
+}, {
+  v: "1";
+  type: string;
+  subject: string;
+  subscriptionId: string;
+  kind: "event";
+  eventId: string;
+  payload?: unknown;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"lifecycle">;
+  subscriptionId: z.ZodString;
+  status: z.ZodEnum<["running", "paused", "completed", "aborted", "failed"]>;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  status: "aborted" | "running" | "paused" | "completed" | "failed";
+  subscriptionId: string;
+  kind: "lifecycle";
+  reason?: string | undefined;
+}, {
+  v: "1";
+  status: "aborted" | "running" | "paused" | "completed" | "failed";
+  subscriptionId: string;
+  kind: "lifecycle";
+  reason?: string | undefined;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"error">;
+  code: z.ZodString;
+  message: z.ZodString;
+  fatal: z.ZodOptional<z.ZodBoolean>;
+  subscriptionId: z.ZodOptional<z.ZodString>;
+  data: z.ZodOptional<z.ZodUnknown>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  code: string;
+  message: string;
+  kind: "error";
+  subscriptionId?: string | undefined;
+  data?: unknown;
+  fatal?: boolean | undefined;
+}, {
+  v: "1";
+  code: string;
+  message: string;
+  kind: "error";
+  subscriptionId?: string | undefined;
+  data?: unknown;
+  fatal?: boolean | undefined;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"pong">;
+  nonce: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  kind: "pong";
+  nonce?: string | undefined;
+}, {
+  v: "1";
+  kind: "pong";
+  nonce?: string | undefined;
+}>, z.ZodObject<{
+  v: z.ZodLiteral<"1">;
+  kind: z.ZodLiteral<"replay-marker">;
+  subscriptionId: z.ZodString;
+  eventId: z.ZodString;
+  droppedCount: z.ZodOptional<z.ZodNumber>;
+  note: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+  v: "1";
+  subscriptionId: string;
+  kind: "replay-marker";
+  eventId: string;
+  droppedCount?: number | undefined;
+  note?: string | undefined;
+}, {
+  v: "1";
+  subscriptionId: string;
+  kind: "replay-marker";
+  eventId: string;
+  droppedCount?: number | undefined;
+  note?: string | undefined;
+}>]>]>;
+/**
+ * Inferred TypeScript union for the `ServerMessage` discriminator.
+ *
+ * @stable
+ */
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+/**
+ * Convenience type aliases for callers that want to reference an
+ * individual variant without `z.infer<typeof X>`.
+ *
+ * @stable
+ */
+type ServerEventFrame = z.infer<typeof EventFrame>;
+/** @stable */
+type ServerLifecycleFrame = z.infer<typeof LifecycleFrame>;
+/** @stable */
+type ServerErrorFrame = z.infer<typeof ErrorFrame>;
+/** @stable */
+type ServerSubscribedFrame = z.infer<typeof SubscribedFrame>;
+/** @stable */
+type ServerUnsubscribedFrame = z.infer<typeof UnsubscribedFrame>;
+/** @stable */
+type ServerPongFrame = z.infer<typeof PongFrame>;
+/** @stable */
+type ServerReplayMarkerFrame = z.infer<typeof ReplayMarkerFrame>;
+/** @stable */
+type ServerRpcSuccess = z.infer<typeof RpcSuccess>;
+/** @stable */
+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
+ */
+declare function isEventFrame(message: ServerMessage): message is ServerEventFrame;
+/** @stable */
+declare function isLifecycleFrame(message: ServerMessage): message is ServerLifecycleFrame;
+/** @stable */
+declare function isErrorFrame(message: ServerMessage): message is ServerErrorFrame;
+/** @stable */
+declare function isSubscribedFrame(message: ServerMessage): message is ServerSubscribedFrame;
+/** @stable */
+declare function isUnsubscribedFrame(message: ServerMessage): message is ServerUnsubscribedFrame;
+/** @stable */
+declare function isPongFrame(message: ServerMessage): message is ServerPongFrame;
+/** @stable */
+declare function isReplayMarkerFrame(message: ServerMessage): message is ServerReplayMarkerFrame;
+/** @stable */
+declare function isRpcSuccess(message: ServerMessage): message is ServerRpcSuccess;
+/** @stable */
+declare function isRpcFailure(message: ServerMessage): message is ServerRpcFailure;
+/**
+ * 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
+ */
+declare const RPC_ERROR_CODES: Readonly<{
+  readonly PARSE_ERROR: -32700;
+  readonly INVALID_REQUEST: -32600;
+  readonly METHOD_NOT_FOUND: -32601;
+  readonly INVALID_PARAMS: -32602;
+  readonly INTERNAL_ERROR: -32603;
+  readonly AUTH_REQUIRED: -32001;
+  readonly AUTH_INVALID: -32002;
+  readonly SCOPE_DENIED: -32003;
+  readonly RATE_LIMITED: -32004;
+  readonly PROTOCOL_VIOLATION: -32005;
+  readonly RUN_NOT_FOUND: -32010;
+  readonly SUBSCRIPTION_NOT_FOUND: -32011;
+}>;
+//#endregion
+export { RPC_ERROR_CODES, ServerErrorFrame, ServerEventFrame, ServerLifecycleFrame, ServerMessage, ServerMessageSchema, ServerPongFrame, ServerReplayMarkerFrame, ServerRpcFailure, ServerRpcSuccess, ServerSubscribedFrame, ServerUnsubscribedFrame, isErrorFrame, isEventFrame, isLifecycleFrame, isPongFrame, isReplayMarkerFrame, isRpcFailure, isRpcSuccess, isSubscribedFrame, isUnsubscribedFrame };
+//# sourceMappingURL=server-message.d.ts.map

package/dist/server-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-message.d.ts","names":[],"sources":["../src/server-message.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/server-message.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+
+//#region src/server-message.ts
+/**
+* `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.
+*
+* Every frame carries the `v: '1'` literal so future revisions can
+* negotiate forward-compatible additions without a subprotocol bump.
+*
+* @packageDocumentation
+*/
+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();
+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
+*/
+const ServerMessageSchema = z.union([RpcFrame, KindedFrame]);
+/**
+* Type guard helpers, one per discriminator. The narrow over the
+* `ServerMessage` union without forcing consumers to memorize the
+* exact field names.
+*
+* @stable
+*/
+function isEventFrame(message) {
+	return "kind" in message && message.kind === "event";
+}
+/** @stable */
+function isLifecycleFrame(message) {
+	return "kind" in message && message.kind === "lifecycle";
+}
+/** @stable */
+function isErrorFrame(message) {
+	return "kind" in message && message.kind === "error";
+}
+/** @stable */
+function isSubscribedFrame(message) {
+	return "kind" in message && message.kind === "subscribed";
+}
+/** @stable */
+function isUnsubscribedFrame(message) {
+	return "kind" in message && message.kind === "unsubscribed";
+}
+/** @stable */
+function isPongFrame(message) {
+	return "kind" in message && message.kind === "pong";
+}
+/** @stable */
+function isReplayMarkerFrame(message) {
+	return "kind" in message && message.kind === "replay-marker";
+}
+/** @stable */
+function isRpcSuccess(message) {
+	return "jsonrpc" in message && message.jsonrpc === "2.0" && "result" in message;
+}
+/** @stable */
+function isRpcFailure(message) {
+	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
+*/
+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
+});
+
+//#endregion
+export { RPC_ERROR_CODES, ServerMessageSchema, isErrorFrame, isEventFrame, isLifecycleFrame, isPongFrame, isReplayMarkerFrame, isRpcFailure, isRpcSuccess, isSubscribedFrame, isUnsubscribedFrame };
+//# sourceMappingURL=server-message.js.map

package/dist/server-message.js.map

@@ -0,0 +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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"}