@scalebun/react-native 1.0.2 → 1.0.3

package/src/vendor/protocol/index.ts

@@ -1,391 +1,391 @@
-/**
- * @scalebun/protocol — Canonical wire-protocol schemas and types
- *
- * Single source of truth for all message schemas shared between the
- * ScaleBun SDK and the ScaleBun Desktop debugger.
- *
- * Constraints:
- *   - Pure TypeScript only — no external runtime deps (no zod), so the package
- *     resolves cleanly under React Native / Metro.
- *   - No React Native, no Electron, no Node-only APIs, no DOM globals.
- *   - Consumable by any future binding (Expo, Flutter codegen, native wrappers).
- *
- * Protocol version: 1  (wire format is UNCHANGED by this refactor)
- */
-
-import { z, type Infer } from './internal/validation';
-
-// Re-export the internal validator so other workspace packages (e.g. the React
-// Native SDK config schema) can share one zod-free implementation.
-export { z } from './internal/validation';
-export type { Infer, SafeParseResult, ValidationIssue, ValidationError } from './internal/validation';
-
-// ─── Protocol Version ────────────────────────────────────────────────────────
-
-export const PROTOCOL_VERSION = 1;
-
-/** Heartbeat interval sent in ACK; SDK uses this for its ping timer */
-export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
-
-// ─── Base Fields (common to all messages) ────────────────────────────────────
-
-const BaseMessageSchema = z.object({
-    protocolVersion: z.number().int().min(1),
-    deviceId: z.string().min(1),
-    sessionId: z.string().min(1),
-    timestamp: z.number(),
-    sequence: z.number().int().min(0),
-});
-
-// ─── Hello / Handshake ──────────────────────────────────────────────────────
-
-export const HelloMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('hello'),
-    payload: z.object({
-        appName: z.string().optional(),
-        appVersion: z.string().optional(),
-        bundleId: z.string().optional(),
-        platform: z.enum(['ios', 'android', 'web']).optional(),
-        osVersion: z.string().optional(),
-        deviceModel: z.string().optional(),
-        sdkVersion: z.string().optional(),
-        buildType: z.enum(['debug', 'release']).optional(),
-        capabilities: z.array(z.string()).optional(),
-        token: z.string().optional(),
-        /**
-         * Shared secret for desktop authentication.
-         *
-         * If the desktop has secret enforcement enabled, the SDK must provide
-         * this field and its value must match the desktop's configured secret.
-         * If enforcement is disabled on the desktop, this field is ignored.
-         *
-         * Optional for backward compatibility: old SDKs that don't send it
-         * will still parse correctly. The desktop decides whether to reject.
-         *
-         * SECURITY NOTE: This is local-network authentication only.
-         * The WS channel is unencrypted (ws://). The secret prevents
-         * unauthorized connections from same-network devices; it does NOT
-         * protect against packet sniffing. For transport encryption, use
-         * TLS (wss://), which is a separate concern.
-         *
-         * Migration path:
-         *   1. Desktop generates a secret on first launch (visible in Connection panel).
-         *   2. Copy the secret and add `secret: '<value>'` to your SDK debug config.
-         *   3. Desktop rejects connections with wrong/missing secret (close code 4401).
-         *   4. To allow old SDKs during migration, toggle "Allow unauthenticated
-         *      connections" ON in the Connection panel.
-         */
-        secret: z.string().optional(),
-        // NOTE: 'deviceName' is accepted by the desktop but absent in the SDK.
-        // Problem 06 tracks this divergence — it will become a one-line addition
-        // here once that task runs.
-
-        /**
-         * Transport-layer statistics reported by the SDK on each hello.
-         * Allows the desktop to surface data-loss warnings when the SDK
-         * buffer overflowed during a disconnect.
-         *
-         * Optional for backward compatibility: old SDKs that don't send it
-         * will still parse correctly.
-         */
-        transportStats: z.object({
-            /** Cumulative count of messages dropped due to buffer overflow. */
-            droppedMessages: z.number().int().min(0),
-        }).optional(),
-    }),
-});
-
-// ─── Event ──────────────────────────────────────────────────────────────────
-
-export const EventCategorySchema = z.enum([
-    'log',
-    'network',
-    'navigation',
-    'lifecycle',
-    'crash',
-    'breadcrumb',
-    'replay',
-    'journey',
-    'session',
-    'performance',
-    'profiler',
-    'export',   // present in SDK; desktop was missing this — Problem 06
-    'custom',
-]);
-
-export const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
-
-/**
- * ─── recordingSessionId Contract ────────────────────────────────────────────
- *
- * The wire envelope's top-level `sessionId` is the TRANSPORT session ID
- * (`debug-xxx`), generated once in `DebugTransport.setIdentity()` when
- * `enableDebug()` is called. It does NOT change between recordings.
- *
- * `payload.data.recordingSessionId` is the RECORDING session ID (`ses-xxx`),
- * generated by `SessionManager.startSession()` each time the user presses
- * "Record". It is null/absent when no recording is active.
- *
- * The desktop uses `recordingSessionId` to correctly correlate network and
- * performance events to the active recording session without relying on the
- * transport ID. When absent (legacy SDK), the desktop falls back to its
- * existing time-bounded ingestion logic.
- *
- * Layers:
- *   SDK Core     → stamps `recordingSessionId` via `DebugEventStream`
- *   Desktop Core → reads it in `shouldIngest()` for precise session correlation
- *
- * Wire envelope is UNCHANGED. Only the event `data` payload gains this field.
- * ────────────────────────────────────────────────────────────────────────────
- */
-export const EventMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('event'),
-    payload: z.object({
-        id: z.string().min(1),
-        category: EventCategorySchema,
-        name: z.string(),
-        data: z.record(z.unknown()).optional(),
-        level: LogLevelSchema.optional(),
-        tags: z.array(z.string()).optional(),
-    }),
-});
-
-// ─── Metric (perf / fps / memory) ───────────────────────────────────────────
-
-export const MetricMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('metric'),
-    payload: z.object({
-        name: z.string(),
-        value: z.number(),
-        unit: z.string().optional(),
-        tags: z.record(z.string()).optional(),
-    }),
-});
-
-// ─── Command (desktop → app) ────────────────────────────────────────────────
-
-export const CommandNameSchema = z.enum([
-    'ping',
-    'setLogLevel',
-    'clearQueue',
-    'triggerFlush',
-    'addBreadcrumb',
-    'startReplay',
-    'stopReplay',
-    'snapshot',
-    'startSession',
-    'stopSession',
-    'captureFrame',
-    'perfCaptureScreen',
-    'journeyRecordToggle',
-    'journeyCaptureStep',
-    'journeySave',
-    'journeyRun',
-    'journeyStopRun',
-    'reloadApp',
-    'exportReportResult',  // present in SDK; desktop was missing this — Problem 06
-]);
-
-export const CommandMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('command'),
-    payload: z.object({
-        commandId: z.string().min(1),
-        name: CommandNameSchema,
-        args: z.record(z.unknown()).optional(),
-    }),
-});
-
-// ─── Command Result (app → desktop) ─────────────────────────────────────────
-
-export const CommandResultMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('command_result'),
-    payload: z.object({
-        commandId: z.string().min(1),
-        success: z.boolean(),
-        data: z.record(z.unknown()).optional(),
-        error: z.string().optional(),
-    }),
-});
-
-// ─── Error ──────────────────────────────────────────────────────────────────
-
-export const ErrorMessageSchema = BaseMessageSchema.extend({
-    type: z.literal('error'),
-    payload: z.object({
-        code: z.string(),
-        message: z.string(),
-        details: z.record(z.unknown()).optional(),
-    }),
-});
-
-// ─── Heartbeat (ping/pong — lightweight, no base fields needed) ─────────────
-
-export const PingMessageSchema = z.object({
-    type: z.literal('scalebun:ping'),
-    deviceId: z.string().min(1),
-    timestamp: z.number(),
-});
-
-export const PongMessageSchema = z.object({
-    type: z.literal('scalebun:pong'),
-    timestamp: z.number(),
-    echoTimestamp: z.number(),
-});
-
-// ─── Ack (server → client after hello) ──────────────────────────────────────
-
-export const AckMessageSchema = z.object({
-    type: z.literal('scalebun:ack'),
-    serverVersion: z.string(),
-    heartbeatIntervalMs: z.number().int().min(1000),
-    timestamp: z.number(),
-});
-
-// ─── Union ──────────────────────────────────────────────────────────────────
-
-export const DebugMessageSchema = z.discriminatedUnion('type', [
-    HelloMessageSchema,
-    EventMessageSchema,
-    MetricMessageSchema,
-    CommandMessageSchema,
-    CommandResultMessageSchema,
-    ErrorMessageSchema,
-]);
-
-// ─── TypeScript Types ────────────────────────────────────────────────────────
-
-export type HelloMessage = Infer<typeof HelloMessageSchema>;
-export type EventMessage = Infer<typeof EventMessageSchema>;
-export type MetricMessage = Infer<typeof MetricMessageSchema>;
-export type CommandMessage = Infer<typeof CommandMessageSchema>;
-export type CommandResultMessage = Infer<typeof CommandResultMessageSchema>;
-export type ErrorMessage = Infer<typeof ErrorMessageSchema>;
-export type PingMessage = Infer<typeof PingMessageSchema>;
-export type PongMessage = Infer<typeof PongMessageSchema>;
-export type AckMessage = Infer<typeof AckMessageSchema>;
-export type DebugMessage = Infer<typeof DebugMessageSchema>;
-
-/** Any message that can be received (including control messages) */
-export type AnyScaleBunMessage = DebugMessage | PingMessage | PongMessage | AckMessage;
-
-export type EventCategory = Infer<typeof EventCategorySchema>;
-export type LogLevel = Infer<typeof LogLevelSchema>;
-export type CommandName = Infer<typeof CommandNameSchema>;
-
-// ─── Desktop-layer Types ─────────────────────────────────────────────────────
-// These live here because they derive from HelloMessage and are consumed by
-// both the Electron main process and the React renderer. They carry no
-// runtime dependencies beyond plain TypeScript.
-
-export type DeviceStatus = 'connected' | 'reconnecting' | 'disconnected';
-
-export interface DeviceInfo {
-    deviceId: string;
-    sessionId: string;
-    appName?: string;
-    appVersion?: string;
-    bundleId?: string;
-    platform?: string;
-    osVersion?: string;
-    deviceModel?: string;
-    deviceName?: string;
-    sdkVersion?: string;
-    buildType?: string;
-    capabilities?: string[];
-    connectedAt: number;
-    lastSeen: number;
-    pingLatencyMs?: number;
-    status: DeviceStatus;
-    /** Cumulative messages dropped by the SDK transport due to buffer overflow. */
-    droppedMessages?: number;
-}
-
-// ─── Safe Parsers (no-throw) ─────────────────────────────────────────────────
-
-export type ParseResult<T> = {
-    success: true;
-    data: T;
-} | {
-    success: false;
-    error: string;
-    raw: unknown;
-};
-
-/**
- * Safely parse a raw message. Returns typed result or error description.
- * Never throws.
- */
-export function parseDebugMessage(raw: unknown): ParseResult<DebugMessage> {
-    try {
-        const result = DebugMessageSchema.safeParse(raw);
-        if (result.success) {
-            return { success: true, data: result.data };
-        }
-        return {
-            success: false,
-            error: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
-            raw,
-        };
-    } catch (e) {
-        return {
-            success: false,
-            error: e instanceof Error ? e.message : 'Unknown parse error',
-            raw,
-        };
-    }
-}
-
-/**
- * Parse any ScaleBun message including control messages (ping/pong/ack).
- * Tries debug message first, then control messages. Never throws.
- */
-export function parseAnyMessage(raw: unknown): ParseResult<AnyScaleBunMessage> {
-    // Try standard debug message first
-    const debugResult = parseDebugMessage(raw);
-    if (debugResult.success) return debugResult;
-
-    // Try control messages
-    try {
-        const obj = raw as Record<string, unknown>;
-        if (obj?.type === 'scalebun:ping') {
-            const r = PingMessageSchema.safeParse(raw);
-            if (r.success) return { success: true, data: r.data };
-        }
-        if (obj?.type === 'scalebun:pong') {
-            const r = PongMessageSchema.safeParse(raw);
-            if (r.success) return { success: true, data: r.data };
-        }
-        if (obj?.type === 'scalebun:ack') {
-            const r = AckMessageSchema.safeParse(raw);
-            if (r.success) return { success: true, data: r.data };
-        }
-    } catch { /* fall through */ }
-
-    return {
-        success: false,
-        error: debugResult.success === false ? debugResult.error : 'Unknown message type',
-        raw,
-    };
-}
-
-/**
- * Safely serialize a message to JSON string. Never throws.
- */
-export function serializeMessage(msg: DebugMessage | PingMessage): string | null {
-    try {
-        return JSON.stringify(msg);
-    } catch {
-        return null;
-    }
-}
-
-/**
- * Safely deserialize a JSON string to a raw object. Never throws.
- */
-export function deserializeMessage(data: string): unknown | null {
-    try {
-        return JSON.parse(data);
-    } catch {
-        return null;
-    }
-}
+/**
+ * @scalebun/protocol — Canonical wire-protocol schemas and types
+ *
+ * Single source of truth for all message schemas shared between the
+ * ScaleBun SDK and the ScaleBun Desktop debugger.
+ *
+ * Constraints:
+ *   - Pure TypeScript only — no external runtime deps (no zod), so the package
+ *     resolves cleanly under React Native / Metro.
+ *   - No React Native, no Electron, no Node-only APIs, no DOM globals.
+ *   - Consumable by any future binding (Expo, Flutter codegen, native wrappers).
+ *
+ * Protocol version: 1  (wire format is UNCHANGED by this refactor)
+ */
+
+import { z, type Infer } from './internal/validation';
+
+// Re-export the internal validator so other workspace packages (e.g. the React
+// Native SDK config schema) can share one zod-free implementation.
+export { z } from './internal/validation';
+export type { Infer, SafeParseResult, ValidationIssue, ValidationError } from './internal/validation';
+
+// ─── Protocol Version ────────────────────────────────────────────────────────
+
+export const PROTOCOL_VERSION = 1;
+
+/** Heartbeat interval sent in ACK; SDK uses this for its ping timer */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+
+// ─── Base Fields (common to all messages) ────────────────────────────────────
+
+const BaseMessageSchema = z.object({
+    protocolVersion: z.number().int().min(1),
+    deviceId: z.string().min(1),
+    sessionId: z.string().min(1),
+    timestamp: z.number(),
+    sequence: z.number().int().min(0),
+});
+
+// ─── Hello / Handshake ──────────────────────────────────────────────────────
+
+export const HelloMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('hello'),
+    payload: z.object({
+        appName: z.string().optional(),
+        appVersion: z.string().optional(),
+        bundleId: z.string().optional(),
+        platform: z.enum(['ios', 'android', 'web']).optional(),
+        osVersion: z.string().optional(),
+        deviceModel: z.string().optional(),
+        sdkVersion: z.string().optional(),
+        buildType: z.enum(['debug', 'release']).optional(),
+        capabilities: z.array(z.string()).optional(),
+        token: z.string().optional(),
+        /**
+         * Shared secret for desktop authentication.
+         *
+         * If the desktop has secret enforcement enabled, the SDK must provide
+         * this field and its value must match the desktop's configured secret.
+         * If enforcement is disabled on the desktop, this field is ignored.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly. The desktop decides whether to reject.
+         *
+         * SECURITY NOTE: This is local-network authentication only.
+         * The WS channel is unencrypted (ws://). The secret prevents
+         * unauthorized connections from same-network devices; it does NOT
+         * protect against packet sniffing. For transport encryption, use
+         * TLS (wss://), which is a separate concern.
+         *
+         * Migration path:
+         *   1. Desktop generates a secret on first launch (visible in Connection panel).
+         *   2. Copy the secret and add `secret: '<value>'` to your SDK debug config.
+         *   3. Desktop rejects connections with wrong/missing secret (close code 4401).
+         *   4. To allow old SDKs during migration, toggle "Allow unauthenticated
+         *      connections" ON in the Connection panel.
+         */
+        secret: z.string().optional(),
+        // NOTE: 'deviceName' is accepted by the desktop but absent in the SDK.
+        // Problem 06 tracks this divergence — it will become a one-line addition
+        // here once that task runs.
+
+        /**
+         * Transport-layer statistics reported by the SDK on each hello.
+         * Allows the desktop to surface data-loss warnings when the SDK
+         * buffer overflowed during a disconnect.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly.
+         */
+        transportStats: z.object({
+            /** Cumulative count of messages dropped due to buffer overflow. */
+            droppedMessages: z.number().int().min(0),
+        }).optional(),
+    }),
+});
+
+// ─── Event ──────────────────────────────────────────────────────────────────
+
+export const EventCategorySchema = z.enum([
+    'log',
+    'network',
+    'navigation',
+    'lifecycle',
+    'crash',
+    'breadcrumb',
+    'replay',
+    'journey',
+    'session',
+    'performance',
+    'profiler',
+    'export',   // present in SDK; desktop was missing this — Problem 06
+    'custom',
+]);
+
+export const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+
+/**
+ * ─── recordingSessionId Contract ────────────────────────────────────────────
+ *
+ * The wire envelope's top-level `sessionId` is the TRANSPORT session ID
+ * (`debug-xxx`), generated once in `DebugTransport.setIdentity()` when
+ * `enableDebug()` is called. It does NOT change between recordings.
+ *
+ * `payload.data.recordingSessionId` is the RECORDING session ID (`ses-xxx`),
+ * generated by `SessionManager.startSession()` each time the user presses
+ * "Record". It is null/absent when no recording is active.
+ *
+ * The desktop uses `recordingSessionId` to correctly correlate network and
+ * performance events to the active recording session without relying on the
+ * transport ID. When absent (legacy SDK), the desktop falls back to its
+ * existing time-bounded ingestion logic.
+ *
+ * Layers:
+ *   SDK Core     → stamps `recordingSessionId` via `DebugEventStream`
+ *   Desktop Core → reads it in `shouldIngest()` for precise session correlation
+ *
+ * Wire envelope is UNCHANGED. Only the event `data` payload gains this field.
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+export const EventMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('event'),
+    payload: z.object({
+        id: z.string().min(1),
+        category: EventCategorySchema,
+        name: z.string(),
+        data: z.record(z.unknown()).optional(),
+        level: LogLevelSchema.optional(),
+        tags: z.array(z.string()).optional(),
+    }),
+});
+
+// ─── Metric (perf / fps / memory) ───────────────────────────────────────────
+
+export const MetricMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('metric'),
+    payload: z.object({
+        name: z.string(),
+        value: z.number(),
+        unit: z.string().optional(),
+        tags: z.record(z.string()).optional(),
+    }),
+});
+
+// ─── Command (desktop → app) ────────────────────────────────────────────────
+
+export const CommandNameSchema = z.enum([
+    'ping',
+    'setLogLevel',
+    'clearQueue',
+    'triggerFlush',
+    'addBreadcrumb',
+    'startReplay',
+    'stopReplay',
+    'snapshot',
+    'startSession',
+    'stopSession',
+    'captureFrame',
+    'perfCaptureScreen',
+    'journeyRecordToggle',
+    'journeyCaptureStep',
+    'journeySave',
+    'journeyRun',
+    'journeyStopRun',
+    'reloadApp',
+    'exportReportResult',  // present in SDK; desktop was missing this — Problem 06
+]);
+
+export const CommandMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('command'),
+    payload: z.object({
+        commandId: z.string().min(1),
+        name: CommandNameSchema,
+        args: z.record(z.unknown()).optional(),
+    }),
+});
+
+// ─── Command Result (app → desktop) ─────────────────────────────────────────
+
+export const CommandResultMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('command_result'),
+    payload: z.object({
+        commandId: z.string().min(1),
+        success: z.boolean(),
+        data: z.record(z.unknown()).optional(),
+        error: z.string().optional(),
+    }),
+});
+
+// ─── Error ──────────────────────────────────────────────────────────────────
+
+export const ErrorMessageSchema = BaseMessageSchema.extend({
+    type: z.literal('error'),
+    payload: z.object({
+        code: z.string(),
+        message: z.string(),
+        details: z.record(z.unknown()).optional(),
+    }),
+});
+
+// ─── Heartbeat (ping/pong — lightweight, no base fields needed) ─────────────
+
+export const PingMessageSchema = z.object({
+    type: z.literal('scalebun:ping'),
+    deviceId: z.string().min(1),
+    timestamp: z.number(),
+});
+
+export const PongMessageSchema = z.object({
+    type: z.literal('scalebun:pong'),
+    timestamp: z.number(),
+    echoTimestamp: z.number(),
+});
+
+// ─── Ack (server → client after hello) ──────────────────────────────────────
+
+export const AckMessageSchema = z.object({
+    type: z.literal('scalebun:ack'),
+    serverVersion: z.string(),
+    heartbeatIntervalMs: z.number().int().min(1000),
+    timestamp: z.number(),
+});
+
+// ─── Union ──────────────────────────────────────────────────────────────────
+
+export const DebugMessageSchema = z.discriminatedUnion('type', [
+    HelloMessageSchema,
+    EventMessageSchema,
+    MetricMessageSchema,
+    CommandMessageSchema,
+    CommandResultMessageSchema,
+    ErrorMessageSchema,
+]);
+
+// ─── TypeScript Types ────────────────────────────────────────────────────────
+
+export type HelloMessage = Infer<typeof HelloMessageSchema>;
+export type EventMessage = Infer<typeof EventMessageSchema>;
+export type MetricMessage = Infer<typeof MetricMessageSchema>;
+export type CommandMessage = Infer<typeof CommandMessageSchema>;
+export type CommandResultMessage = Infer<typeof CommandResultMessageSchema>;
+export type ErrorMessage = Infer<typeof ErrorMessageSchema>;
+export type PingMessage = Infer<typeof PingMessageSchema>;
+export type PongMessage = Infer<typeof PongMessageSchema>;
+export type AckMessage = Infer<typeof AckMessageSchema>;
+export type DebugMessage = Infer<typeof DebugMessageSchema>;
+
+/** Any message that can be received (including control messages) */
+export type AnyScaleBunMessage = DebugMessage | PingMessage | PongMessage | AckMessage;
+
+export type EventCategory = Infer<typeof EventCategorySchema>;
+export type LogLevel = Infer<typeof LogLevelSchema>;
+export type CommandName = Infer<typeof CommandNameSchema>;
+
+// ─── Desktop-layer Types ─────────────────────────────────────────────────────
+// These live here because they derive from HelloMessage and are consumed by
+// both the Electron main process and the React renderer. They carry no
+// runtime dependencies beyond plain TypeScript.
+
+export type DeviceStatus = 'connected' | 'reconnecting' | 'disconnected';
+
+export interface DeviceInfo {
+    deviceId: string;
+    sessionId: string;
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    sdkVersion?: string;
+    buildType?: string;
+    capabilities?: string[];
+    connectedAt: number;
+    lastSeen: number;
+    pingLatencyMs?: number;
+    status: DeviceStatus;
+    /** Cumulative messages dropped by the SDK transport due to buffer overflow. */
+    droppedMessages?: number;
+}
+
+// ─── Safe Parsers (no-throw) ─────────────────────────────────────────────────
+
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+    raw: unknown;
+};
+
+/**
+ * Safely parse a raw message. Returns typed result or error description.
+ * Never throws.
+ */
+export function parseDebugMessage(raw: unknown): ParseResult<DebugMessage> {
+    try {
+        const result = DebugMessageSchema.safeParse(raw);
+        if (result.success) {
+            return { success: true, data: result.data };
+        }
+        return {
+            success: false,
+            error: result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '),
+            raw,
+        };
+    } catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : 'Unknown parse error',
+            raw,
+        };
+    }
+}
+
+/**
+ * Parse any ScaleBun message including control messages (ping/pong/ack).
+ * Tries debug message first, then control messages. Never throws.
+ */
+export function parseAnyMessage(raw: unknown): ParseResult<AnyScaleBunMessage> {
+    // Try standard debug message first
+    const debugResult = parseDebugMessage(raw);
+    if (debugResult.success) return debugResult;
+
+    // Try control messages
+    try {
+        const obj = raw as Record<string, unknown>;
+        if (obj?.type === 'scalebun:ping') {
+            const r = PingMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+        if (obj?.type === 'scalebun:pong') {
+            const r = PongMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+        if (obj?.type === 'scalebun:ack') {
+            const r = AckMessageSchema.safeParse(raw);
+            if (r.success) return { success: true, data: r.data };
+        }
+    } catch { /* fall through */ }
+
+    return {
+        success: false,
+        error: debugResult.success === false ? debugResult.error : 'Unknown message type',
+        raw,
+    };
+}
+
+/**
+ * Safely serialize a message to JSON string. Never throws.
+ */
+export function serializeMessage(msg: DebugMessage | PingMessage): string | null {
+    try {
+        return JSON.stringify(msg);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Safely deserialize a JSON string to a raw object. Never throws.
+ */
+export function deserializeMessage(data: string): unknown | null {
+    try {
+        return JSON.parse(data);
+    } catch {
+        return null;
+    }
+}