sonamu 0.10.11 → 0.10.13

package/src/stream/ws-telemetry.ts

@@ -1,6 +1,23 @@
+import { runtimeTypeOf } from "../runtime-type";
+import { isFunctionValue, isObjectValue } from "../utils/runtime-value";
 import { InMemoryEventStore, InMemoryMetricStore, InMemorySpanStore } from "./ws-telemetry-memory";
 import { generateSpanId, generateTraceId, parseTraceParent } from "./ws-telemetry-trace";
 
+export type WebSocketTelemetryValue =
+  | null
+  | undefined
+  | bigint
+  | boolean
+  | number
+  | string
+  | Date
+  | WebSocketTelemetryValue[]
+  | WebSocketTelemetryAttributes;
+
+export interface WebSocketTelemetryAttributes {
+  [key: string]: WebSocketTelemetryValue;
+}
+
 // -- Record types (unchanged) --
 
 export type WebSocketTelemetryRecordBase = {
@@ -24,7 +41,7 @@ export type WebSocketTelemetryEventRecord = WebSocketTelemetryRecordBase & {
   name: string;
   level: "debug" | "info" | "warn" | "error";
   attributes?: Record<string, string | number | boolean>;
-  detail?: Record<string, unknown>;
+  detail?: WebSocketTelemetryAttributes;
   payloadPreview?: string;
 };
 
@@ -49,12 +66,12 @@ export type WebSocketTelemetrySpanRecord = WebSocketTelemetryRecordBase & {
   events?: Array<{
     name: string;
     timestamp: number;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
   links?: Array<{
     traceId: string;
     spanId: string;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
 };
 
@@ -72,8 +89,8 @@ export type WebSocketTelemetryEventInput = {
   connectionId?: string;
   userId?: string;
   attributes?: Record<string, string | number | boolean>;
-  detail?: Record<string, unknown>;
-  payload?: unknown;
+  detail?: WebSocketTelemetryAttributes;
+  payload?: WebSocketTelemetryValue;
   traceId?: string;
   spanId?: string;
   parentSpanId?: string;
@@ -113,12 +130,12 @@ export type WebSocketSpanInput = {
   events?: Array<{
     name: string;
     timestamp: number;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
   links?: Array<{
     traceId: string;
     spanId: string;
-    attributes?: Record<string, unknown>;
+    attributes?: WebSocketTelemetryAttributes;
   }>;
 };
 
@@ -434,7 +451,7 @@ function isSensitiveKey(key: string): boolean {
   return SENSITIVE_KEY_PATTERNS.some((pattern) => normalized.includes(pattern));
 }
 
-function redactValue(value: unknown, key?: string): unknown {
+function redactValue(value: WebSocketTelemetryValue, key?: string): WebSocketTelemetryValue {
   if (key !== undefined && isSensitiveKey(key)) {
     return REDACTED_VALUE;
   }
@@ -447,8 +464,8 @@ function redactValue(value: unknown, key?: string): unknown {
     return value;
   }
 
-  if (value && typeof value === "object") {
-    const redacted: Record<string, unknown> = {};
+  if (value && isObjectValue(value)) {
+    const redacted: WebSocketTelemetryAttributes = {};
     for (const [childKey, childValue] of Object.entries(value)) {
       redacted[childKey] = redactValue(childValue, childKey);
     }
@@ -464,6 +481,7 @@ function redactValue(value: unknown, key?: string): unknown {
  */
 function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketTelemetryRecord {
   if (record.type === "event") {
+    // SAFETY: redactor는 이벤트 레코드의 키 구조를 유지하고 값만 마스킹한다.
     return {
       ...record,
       attributes: record.attributes
@@ -477,6 +495,7 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
   }
 
   if (record.type === "metric") {
+    // SAFETY: redactor는 메트릭 레코드의 키 구조를 유지하고 값만 마스킹한다.
     return {
       ...record,
       tags: record.tags
@@ -486,6 +505,7 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
     };
   }
 
+  // SAFETY: redactor는 span과 하위 이벤트·링크의 키 구조를 유지하고 값만 마스킹한다.
   return {
     ...record,
     attributes: record.attributes
@@ -494,19 +514,19 @@ function defaultSensitiveKeyRedact(record: WebSocketTelemetryRecord): WebSocketT
     events: record.events?.map((event) => ({
       ...event,
       attributes: event.attributes
-        ? (redactValue(event.attributes) as Record<string, unknown>)
+        ? (redactValue(event.attributes) as WebSocketTelemetryAttributes)
         : undefined,
     })),
     links: record.links?.map((link) => ({
       ...link,
       attributes: link.attributes
-        ? (redactValue(link.attributes) as Record<string, unknown>)
+        ? (redactValue(link.attributes) as WebSocketTelemetryAttributes)
         : undefined,
     })),
   };
 }
 
-function truncatePayloadPreview(payload: unknown, maxBytes: number): string {
+function truncatePayloadPreview(payload: WebSocketTelemetryValue, maxBytes: number): string {
   try {
     const serialized = JSON.stringify(redactValue(payload));
     if (Buffer.byteLength(serialized, "utf-8") <= maxBytes) {
@@ -536,8 +556,8 @@ function truncateUtf8String(value: string, maxBytes: number): string {
   return result + suffix;
 }
 
-export function isPromiseLike(value: unknown): value is Promise<void> {
-  return typeof value === "object" && value !== null && "then" in value && "catch" in value;
+export function isPromiseLike<Value>(value: Value): value is Value & Promise<void> {
+  return isObjectValue(value) && value !== null && "then" in value && "catch" in value;
 }
 
 // -- TokenBucket (unchanged) --
@@ -679,7 +699,7 @@ type ResolvedSpanPipelineOptions = {
 type InternalEventReporter = (
   name: string,
   level: WebSocketTelemetryEventRecord["level"],
-  detail?: Record<string, unknown>,
+  detail?: WebSocketTelemetryAttributes,
 ) => void;
 
 // -- TelemetryPipeline (abstract) --
@@ -695,7 +715,7 @@ abstract class TelemetryPipeline<
 > {
   abstract readonly signal: "event" | "metric" | "span";
   protected readonly sinks: TSink[];
-  protected readonly _store: TStore;
+  protected readonly telemetryStore: TStore;
   protected readonly tokenBucket: TokenBucket;
   protected readonly maxInFlightEmits: number;
   protected readonly runtimeMetadata: RuntimeMetadata;
@@ -717,7 +737,7 @@ abstract class TelemetryPipeline<
     runtimeMetadata: RuntimeMetadata,
   ) {
     this.sinks = sinks;
-    this._store = store;
+    this.telemetryStore = store;
     this.tokenBucket = new TokenBucket(maxRecordsPerSecond, maxRecordsPerSecond);
     this.maxInFlightEmits = maxInFlightEmits;
     this.sharedRedactor = sharedRedactor;
@@ -726,7 +746,7 @@ abstract class TelemetryPipeline<
   }
 
   get store(): TStore {
-    return this._store;
+    return this.telemetryStore;
   }
 
   setInternalEventReporter(reporter: InternalEventReporter): void {
@@ -772,7 +792,8 @@ abstract class TelemetryPipeline<
         this.droppedCount += 1;
         return;
       }
-      prepared = afterDefault as TRecord;
+      prepared =
+        /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ afterDefault as TRecord;
     } catch {
       this.droppedCount += 1;
       return;
@@ -860,7 +881,7 @@ abstract class TelemetryPipeline<
     }
 
     // result.type === record.type === TRecord["type"]이므로 narrowed TRecord로 안전하게 좁힐 수 있다.
-    return result as TRecord;
+    return /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ result as TRecord;
   }
 
   protected dispatchToSinks(record: TRecord, selfObserveFailures = true): void {
@@ -885,9 +906,9 @@ abstract class TelemetryPipeline<
             () => {
               this.decrementInFlightEmit(sink);
             },
-            (error: unknown) => {
+            (cause: unknown) => {
               this.decrementInFlightEmit(sink);
-              this.observeSinkFailure("emit", error, selfObserveFailures);
+              this.observeSinkFailure("emit", cause, selfObserveFailures);
             },
           );
         }
@@ -906,9 +927,9 @@ abstract class TelemetryPipeline<
     this.inFlightEmits.set(sink, current - 1);
   }
 
-  private observeSinkFailure(
+  private observeSinkFailure<Value>(
     phase: "emit" | "shutdown",
-    error: unknown,
+    error: Value,
     selfObserveFailure: boolean,
   ): void {
     this.sinkFailureCount += 1;
@@ -916,14 +937,14 @@ abstract class TelemetryPipeline<
     this.dispatchInternalEvent("ws.telemetry.sink.failed", "warn", {
       phase,
       signal: this.signal,
-      errorType: error instanceof Error ? error.name : typeof error,
+      errorType: error instanceof Error ? error.name : runtimeTypeOf(error),
     });
   }
 
   protected dispatchInternalEvent(
     name: string,
     level: WebSocketTelemetryEventRecord["level"],
-    detail?: Record<string, unknown>,
+    detail?: WebSocketTelemetryAttributes,
   ): void {
     if (this.internalEventReporter === undefined) return;
     try {
@@ -953,8 +974,8 @@ abstract class TelemetryPipeline<
       let timeout: ReturnType<typeof setTimeout> | null = null;
       const shutdownPromise = result.then(
         () => "completed" as const,
-        (error: unknown) => {
-          throw error;
+        (cause: unknown) => {
+          throw cause;
         },
       );
       const timeoutPromise = new Promise<"timeout">((resolve) => {
@@ -1056,7 +1077,7 @@ class EventPipeline extends TelemetryPipeline<
   dispatchInternalDiagnosticEvent(
     name: string,
     level: WebSocketTelemetryEventRecord["level"],
-    detail?: Record<string, unknown>,
+    detail?: WebSocketTelemetryAttributes,
   ): void {
     const record: WebSocketTelemetryEventRecord = {
       type: "event",
@@ -1172,7 +1193,7 @@ class MetricPipeline extends TelemetryPipeline<
 
       if (
         this.collectionInterval &&
-        typeof this.collectionInterval === "object" &&
+        isObjectValue(this.collectionInterval) &&
         "unref" in this.collectionInterval
       ) {
         this.collectionInterval.unref();
@@ -1595,28 +1616,30 @@ function buildController(
   // 신호별 redactor / beforeRecord 해석.
   // null이면 sharedRedactor를 undefined로 덮어써 step 2 자체를 skip한다.
   const eventsSharedRedactor = eventsOpt.redactor === null ? undefined : defaults.redactor;
-  const eventsSignalRedactor =
-    typeof eventsOpt.redactor === "function" ? eventsOpt.redactor : undefined;
+  const eventsSignalRedactor = isFunctionValue(eventsOpt.redactor) ? eventsOpt.redactor : undefined;
   const eventsSharedBeforeRecord =
     eventsOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const eventsSignalBeforeRecord =
-    typeof eventsOpt.beforeRecord === "function" ? eventsOpt.beforeRecord : undefined;
+  const eventsSignalBeforeRecord = isFunctionValue(eventsOpt.beforeRecord)
+    ? eventsOpt.beforeRecord
+    : undefined;
 
   const metricsSharedRedactor = metricsOpt.redactor === null ? undefined : defaults.redactor;
-  const metricsSignalRedactor =
-    typeof metricsOpt.redactor === "function" ? metricsOpt.redactor : undefined;
+  const metricsSignalRedactor = isFunctionValue(metricsOpt.redactor)
+    ? metricsOpt.redactor
+    : undefined;
   const metricsSharedBeforeRecord =
     metricsOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const metricsSignalBeforeRecord =
-    typeof metricsOpt.beforeRecord === "function" ? metricsOpt.beforeRecord : undefined;
+  const metricsSignalBeforeRecord = isFunctionValue(metricsOpt.beforeRecord)
+    ? metricsOpt.beforeRecord
+    : undefined;
 
   const spansSharedRedactor = spansOpt.redactor === null ? undefined : defaults.redactor;
-  const spansSignalRedactor =
-    typeof spansOpt.redactor === "function" ? spansOpt.redactor : undefined;
+  const spansSignalRedactor = isFunctionValue(spansOpt.redactor) ? spansOpt.redactor : undefined;
   const spansSharedBeforeRecord =
     spansOpt.beforeRecord === null ? undefined : defaults.beforeRecord;
-  const spansSignalBeforeRecord =
-    typeof spansOpt.beforeRecord === "function" ? spansOpt.beforeRecord : undefined;
+  const spansSignalBeforeRecord = isFunctionValue(spansOpt.beforeRecord)
+    ? spansOpt.beforeRecord
+    : undefined;
 
   // events
   const eventSinks: WebSocketTelemetryEventSink[] = eventsOpt.sinks ? [...eventsOpt.sinks] : [];

package/src/stream/ws.ts

@@ -1,9 +1,12 @@
 import { randomUUID } from "node:crypto";
+import { type EventEmitter } from "node:events";
 import { hostname } from "node:os";
 
-import { type WebSocket } from "ws";
+import { type RawData, type WebSocket } from "ws";
 import { z } from "zod";
 
+import { runtimeTypeOf } from "../runtime-type";
+import { isStringValue } from "../utils/runtime-value";
 import { type WebSocketAudience } from "./ws-audience";
 import { type WebSocketClusterBus } from "./ws-cluster-bus";
 import { type WebSocketPresenceStore } from "./ws-presence-store";
@@ -46,7 +49,7 @@ const OUTBOUND_RETRY_DELAY_MS = 5;
 // meta는 optional이므로 기존 `{event, data}` 메시지도 그대로 파싱됨 (backward-compatible)
 const WebSocketEnvelopeSchema = z.object({
   event: z.string(),
-  data: z.unknown(),
+  data: z.json(),
   meta: z
     .object({
       traceparent: z.string().optional(),
@@ -61,17 +64,25 @@ type MessageHandler<T> = (
 ) => void | Promise<void>;
 type CloseHandler = () => void | Promise<void>;
 
-export type WebSocketEventMap = Record<string, unknown>;
+export type WebSocketEventMap<EventPayload = never> = Record<string, EventPayload>;
+export type WebSocketTransport = Pick<
+  WebSocket,
+  "bufferedAmount" | "close" | "ping" | "readyState" | "send" | "terminate"
+> & {
+  off: (...args: Parameters<EventEmitter["off"]>) => void;
+  on: (...args: Parameters<EventEmitter["on"]>) => void;
+};
 
-type InferWebSocketEventMap<TSchema extends z.ZodRawShape> = z.infer<z.ZodObject<TSchema>>;
+type WebSocketEventFields = Record<string, z.ZodType>;
+type InferWebSocketEventMap<TSchema extends WebSocketEventFields> = z.infer<z.ZodObject<TSchema>>;
 
-export type WebSocketOutEvents<TOut extends WebSocketEventMap = WebSocketEventMap> = TOut;
+export type WebSocketOutEvents<TOut extends object = WebSocketEventMap> = TOut;
 
-export type WebSocketInEvents<TIn extends WebSocketEventMap = WebSocketEventMap> = TIn;
+export type WebSocketInEvents<TIn extends object = WebSocketEventMap> = TIn;
 
 export interface WebSocketConnection<
-  TOut extends WebSocketEventMap = WebSocketEventMap,
-  TIn extends WebSocketEventMap = WebSocketEventMap,
+  TOut extends object = WebSocketEventMap,
+  TIn extends object = WebSocketEventMap,
 > extends ManagedWebSocketConnection {
   transport: "ws";
   onClose(callback: CloseHandler): void;
@@ -90,11 +101,14 @@ export interface WebSocketConnection<
   clearUserId(): void;
 }
 
-export type AnyWebSocketConnection = WebSocketConnection<WebSocketEventMap, WebSocketEventMap>;
+export type AnyWebSocketConnection = WebSocketConnection<object, object>;
 
 type ParsedEnvelope = z.infer<typeof WebSocketEnvelopeSchema>;
 
-type WebSocketConnectionOptions<TOut extends z.ZodRawShape, TIn extends z.ZodRawShape> = {
+type WebSocketConnectionOptions<
+  TOut extends WebSocketEventFields,
+  TIn extends WebSocketEventFields,
+> = {
   namespace?: string;
   heartbeat?: number;
   active?: boolean;
@@ -137,8 +151,11 @@ export class WebSocketRuntime {
     this.registry = new WebSocketRegistry(registryOptions);
   }
 
-  registerConnection<TOutSchema extends z.ZodRawShape, TInSchema extends z.ZodRawShape>(
-    socket: WebSocket,
+  registerConnection<
+    TOutSchema extends WebSocketEventFields,
+    TInSchema extends WebSocketEventFields,
+  >(
+    socket: WebSocketTransport,
     options: Omit<
       WebSocketConnectionOptions<TOutSchema, TInSchema>,
       "registry" | "telemetryController"
@@ -155,19 +172,29 @@ export class WebSocketRuntime {
     this.registry.activate(connectionId);
   }
 
-  broadcast(event: string, data: unknown, namespace?: string): void {
+  broadcast<Data>(event: string, data: Data, namespace?: string): void {
     this.registry.broadcast(event, data, namespace);
   }
 
-  publishToRoom(roomId: WebSocketRoomId, event: string, data: unknown, namespace?: string): void {
+  publishToRoom<Data>(
+    roomId: WebSocketRoomId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.registry.publishToRoom(roomId, event, data, namespace);
   }
 
-  publishToUser(userId: WebSocketUserId, event: string, data: unknown, namespace?: string): void {
+  publishToUser<Data>(
+    userId: WebSocketUserId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.registry.publishToUser(userId, event, data, namespace);
   }
 
-  publishToAudience(audience: WebSocketAudience, event: string, data: unknown): void {
+  publishToAudience<Data>(audience: WebSocketAudience, event: string, data: Data): void {
     this.registry.publishToAudience(audience, event, data);
   }
 
@@ -185,7 +212,10 @@ export function createWebSocketRuntime(options: WebSocketRuntimeOptions = {}): W
   return new WebSocketRuntime(options);
 }
 
-class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extends z.ZodRawShape>
+class WebSocketConnectionImpl<
+  TOutSchema extends WebSocketEventFields,
+  TInSchema extends WebSocketEventFields,
+>
   implements
     WebSocketConnection<InferWebSocketEventMap<TOutSchema>, InferWebSocketEventMap<TInSchema>>,
     TelemetryInspectableConnection,
@@ -212,10 +242,10 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   private readonly connectionStartedAt = performance.now();
 
   // connection 수명 동안 유지되는 식별자. setUserId/clearUserId로 업데이트되며 emit hot path에서 매번 registry lookup하지 않도록 캐시함
-  private _userId?: string;
+  private currentUserId?: string;
 
   get userId(): string | undefined {
-    return this._userId;
+    return this.currentUserId;
   }
 
   private closedInternal = false;
@@ -226,7 +256,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   private outboundFlushScheduled = false;
 
   constructor(
-    private readonly socket: WebSocket,
+    private readonly socket: WebSocketTransport,
     private readonly options: WebSocketConnectionOptions<TOutSchema, TInSchema>,
   ) {
     this.namespace = options.namespace ?? "default";
@@ -235,8 +265,8 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
     this.connectionSpanId = options.spanId;
     this.connectionParentSpanId = options.parentSpanId;
     this.connectionSampled = options.sampled;
-    this.eventSchemasIn = options.inEvents.shape as unknown as Record<string, z.ZodTypeAny>;
-    this.eventSchemasOut = options.outEvents.shape as unknown as Record<string, z.ZodTypeAny>;
+    this.eventSchemasIn = options.inEvents["shape"];
+    this.eventSchemasOut = options.outEvents["shape"];
 
     let resolveClosePromise!: () => void;
     this.closePromise = new Promise<void>((resolve) => {
@@ -266,7 +296,9 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   ): void {
     const eventKey = String(event);
     const handlers = this.messageHandlers.get(eventKey) ?? [];
-    handlers.push(handler as MessageHandler<unknown>);
+    handlers.push(
+      /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ handler as MessageHandler<unknown>,
+    );
     this.messageHandlers.set(eventKey, handlers);
     this.flushPendingMessages(eventKey);
   }
@@ -278,7 +310,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
     this.publishValidated(String(event), data);
   }
 
-  publishUntyped(event: string, data: unknown): void {
+  publishUntyped<Data>(event: string, data: Data): void {
     this.publishValidated(event, data);
   }
 
@@ -295,12 +327,12 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   }
 
   setUserId(userId: WebSocketUserId): void {
-    this._userId = String(userId);
+    this.currentUserId = String(userId);
     this.options.registry.setUserId(this.id, userId);
   }
 
   clearUserId(): void {
-    this._userId = undefined;
+    this.currentUserId = undefined;
     this.options.registry.clearUserId(this.id);
   }
 
@@ -327,7 +359,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
     return {
       connectionId: this.id,
       namespace: this.namespace,
-      userId: this._userId,
+      userId: this.currentUserId,
       traceId: this.connectionTraceId,
       spanId: this.connectionSpanId,
       parentSpanId: this.connectionParentSpanId,
@@ -368,7 +400,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   }
 
   // 인바운드 메시지를 순차 처리 큐에 올림. Sonamu envelope 검증 수행
-  private readonly handleMessage = (raw: unknown) => {
+  private readonly handleMessage = (raw: RawData) => {
     this.enqueueMessageTask(async () => {
       const text = normalizeMessage(raw);
       const parsedEnvelope = safeParseEnvelope(text);
@@ -391,7 +423,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   };
 
   private readonly handleClose = (code?: number, reason?: Buffer | string) => {
-    const reasonText = typeof reason === "string" ? reason : reason?.toString();
+    const reasonText = isStringValue(reason) ? reason : reason?.toString();
     this.markClosed(code, reasonText);
   };
 
@@ -487,7 +519,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
     const messageTraceFields = {
       connectionId: this.id,
       namespace: this.namespace,
-      userId: this._userId,
+      userId: this.currentUserId,
       traceId: traceCtx.traceId,
       spanId: traceCtx.spanId,
       parentSpanId: traceCtx.parentSpanId,
@@ -545,7 +577,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
     }
   }
 
-  private publishValidated(event: string, data: unknown): void {
+  private publishValidated<Data>(event: string, data: Data): void {
     const schema = this.eventSchemasOut[event];
     if (!schema) {
       this.options.telemetryController.emit({
@@ -584,7 +616,6 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
         data: parsed.data,
       }),
       event,
-      parsed.data,
     );
   }
 
@@ -705,8 +736,8 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   }
 
   // queue가 한계에 도달하면 1013으로 닫아 느린 소비자가 메모리를 끝없이 잡아먹지 못하게 함
-  // data 인자는 telemetry payload preview 용도로만 사용하며 pendingOutboundMessages에는 저장하지 않음 (큐 메모리 보호)
-  private enqueueOutboundMessage(payload: string, event: string, data: unknown): void {
+  // telemetry preview는 직렬화된 payload에서 복원해 전송 데이터와 같은 JSON 계약을 유지함
+  private enqueueOutboundMessage(payload: string, event: string): void {
     if (this.pendingOutboundMessages.length >= MAX_PENDING_OUTBOUND_MESSAGES) {
       this.options.telemetryController.emit({
         name: "ws.backpressure.overflow",
@@ -723,7 +754,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
       level: "debug",
       ...this.telemetryFields(),
       detail: { event },
-      payload: data,
+      payload: safeParseEnvelope(payload)?.data,
     });
     this.scheduleOutboundFlush();
   }
@@ -818,7 +849,7 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
           status: "error",
           ...fields,
           attributes: { event },
-          errorType: error instanceof Error ? error.name : typeof error,
+          errorType: error instanceof Error ? error.name : runtimeTypeOf(error),
         });
         this.close(WS_CLOSE_CODE_INTERNAL_ERROR, "Outbound publish failed");
         return;
@@ -838,8 +869,8 @@ class WebSocketConnectionImpl<TOutSchema extends z.ZodRawShape, TInSchema extend
   }
 }
 
-function normalizeMessage(raw: unknown): string {
-  if (typeof raw === "string") {
+function normalizeMessage(raw: RawData): string {
+  if (isStringValue(raw)) {
     return raw;
   }
 
@@ -862,7 +893,10 @@ function normalizeMessage(raw: unknown): string {
 
 function safeParseEnvelope(raw: string): ParsedEnvelope | null {
   try {
-    const parsed = JSON.parse(raw) as unknown;
+    const parsed =
+      /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+        raw,
+      ) as unknown;
     const validated = WebSocketEnvelopeSchema.safeParse(parsed);
     return validated.success ? validated.data : null;
   } catch {

package/src/syncer/__tests__/api-parser.websocket-type-ref.test.ts

@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { z } from "zod";
 
 import { registeredApis } from "../../api/decorators";
+import { type AbsolutePath } from "../../utils/path-utils";
 import { readApisFromFile } from "../api-parser";
 
 describe("readApisFromFile websocket type refs", () => {
@@ -47,7 +48,7 @@ describe("readApisFromFile websocket type refs", () => {
     });
 
     tempDir = await mkdtemp(path.join(tmpdir(), "sonamu-api-parser-"));
-    const filePath = path.join(tempDir, "chat.frame.ts");
+    const filePath: AbsolutePath = `/${path.relative("/", path.join(tempDir, "chat.frame.ts"))}`;
     await writeFile(
       filePath,
       `
@@ -64,7 +65,7 @@ class ChatFrameClass {
       `.trim(),
     );
 
-    const [api] = await readApisFromFile(filePath as `${string}.ts`);
+    const [api] = await readApisFromFile(filePath);
 
     expect(api?.websocketOptions?.outEventsTypeRef).toEqual({
       t: "ref",