sonamu 0.10.12 → 0.10.13

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",

package/src/syncer/__tests__/http-validator-registry.test.ts

@@ -0,0 +1,137 @@
+import { access, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { type SonamuConfig } from "../../api/config";
+import { Sonamu } from "../../api/sonamu";
+import { type AbsolutePath } from "../../utils/path-utils";
+import { Syncer, type SyncerDependencies } from "../syncer";
+import { actionGenerateHttpValidators } from "../syncer-actions";
+
+function toAbsolutePath(filePath: string): AbsolutePath {
+  if (!path.isAbsolute(filePath)) {
+    throw new Error(`절대 경로가 필요합니다: ${filePath}`);
+  }
+  // SAFETY: path.isAbsolute 검사로 AbsolutePath 계약을 확인했다.
+  return filePath as AbsolutePath;
+}
+
+function createDependencies() {
+  return {
+    actionCopySharedToTargetsIfNotExists: vi
+      .fn<SyncerDependencies["actionCopySharedToTargetsIfNotExists"]>()
+      .mockResolvedValue(undefined),
+    actionGenerateHttpValidators: vi.fn<SyncerDependencies["actionGenerateHttpValidators"]>(),
+    actionGenerateSsrEntryServerIfNotExists: vi
+      .fn<SyncerDependencies["actionGenerateSsrEntryServerIfNotExists"]>()
+      .mockResolvedValue([]),
+    findChangedFilesUsingChecksums: vi.fn<SyncerDependencies["findChangedFilesUsingChecksums"]>(),
+    renewChecksums: vi.fn<SyncerDependencies["renewChecksums"]>().mockResolvedValue(undefined),
+  } satisfies SyncerDependencies;
+}
+
+const testConfig = {
+  api: { dir: "api", route: { prefix: "/api" } },
+  i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+  sync: { targets: [] },
+  database: {},
+  server: {
+    apiConfig: {
+      contextProvider: (defaultContext) => defaultContext,
+      guardHandler: () => undefined,
+    },
+  },
+} satisfies SonamuConfig;
+
+describe("HTTP validator registry sync 정리", () => {
+  const tempRoots: string[] = [];
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await Promise.all(
+      tempRoots.splice(0).map((rootPath) => rm(rootPath, { recursive: true, force: true })),
+    );
+  });
+
+  it.each([
+    { label: "opt-out", value: false as const },
+    { label: "JIT", value: { api: "jit" as const } },
+  ])("$label 정책은 남아 있는 generated registry를 제거한다", async ({ value }) => {
+    const apiRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-registry-sync-test-"));
+    tempRoots.push(apiRootPath);
+    const registryPath = path.join(apiRootPath, "src/application/sonamu.validators.generated.ts");
+    await mkdir(path.dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, "export const validators = new Map();\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      api: { ...testConfig.api, dir: "." },
+      validation: { zodCompiler: value },
+    };
+
+    await actionGenerateHttpValidators();
+
+    await expect(access(registryPath)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("registry-only drift를 경고로 넘기지 않고 즉시 재생성한다", async () => {
+    const appRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-registry-drift-test-"));
+    tempRoots.push(appRootPath);
+    const apiRootPath = path.join(appRootPath, "api");
+    const registryPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/sonamu.validators.generated.ts"),
+    );
+    await mkdir(path.dirname(registryPath), { recursive: true });
+    await writeFile(registryPath, "// drifted registry\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      validation: { zodCompiler: { api: "aot" } },
+    };
+    const dependencies = createDependencies();
+    dependencies.actionGenerateHttpValidators.mockResolvedValue(registryPath);
+    dependencies.findChangedFilesUsingChecksums.mockResolvedValue([registryPath]);
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await new Syncer(dependencies).sync();
+
+    expect(dependencies.actionGenerateHttpValidators).toHaveBeenCalledTimes(1);
+    expect(dependencies.renewChecksums).toHaveBeenCalledTimes(1);
+  });
+
+  it("삭제된 registry가 checksum 변경 목록에서 빠져도 다른 tracked 변경 처리 중 복구한다", async () => {
+    const appRootPath = await mkdtemp(path.join(os.tmpdir(), "sonamu-missing-registry-test-"));
+    tempRoots.push(appRootPath);
+    const apiRootPath = path.join(appRootPath, "api");
+    const registryPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/sonamu.validators.generated.ts"),
+    );
+    const unrelatedPath = toAbsolutePath(
+      path.join(apiRootPath, "src/application/queries.generated.ts"),
+    );
+    await mkdir(path.dirname(unrelatedPath), { recursive: true });
+    await writeFile(unrelatedPath, "// unrelated tracked change\n");
+    Sonamu.apiRootPath = toAbsolutePath(apiRootPath);
+    Sonamu.config = {
+      ...testConfig,
+      validation: { zodCompiler: { api: "aot" } },
+    };
+    const order: string[] = [];
+    const dependencies = createDependencies();
+    dependencies.actionGenerateHttpValidators.mockImplementation(async () => {
+      order.push("registry");
+      return registryPath;
+    });
+    dependencies.findChangedFilesUsingChecksums.mockResolvedValue([unrelatedPath]);
+    dependencies.renewChecksums.mockImplementation(async () => {
+      order.push("checksum");
+    });
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await new Syncer(dependencies).sync();
+
+    expect(order).toEqual(["registry", "checksum"]);
+  });
+});

package/src/syncer/api-parser.ts

@@ -77,7 +77,7 @@ export async function readApisFromFile(filePath: AbsolutePath): Promise<Extended
         return resolveParamDec(
           {
             name: paramDec.name,
-            type: paramDec.type as ts.TypeNode,
+            type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ paramDec.type as ts.TypeNode,
             optional: paramDec.questionToken !== undefined || paramDec.initializer !== undefined,
             defaultDef,
           },
@@ -253,7 +253,10 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.VoidKeyword:
       return "void";
     case ts.SyntaxKind.LiteralType: {
-      const literal = (typeNode as ts.LiteralTypeNode).literal;
+      const literal =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.LiteralTypeNode
+        ).literal;
       if (ts.isStringLiteral(literal)) {
         return {
           t: "string-literal",
@@ -278,35 +281,46 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
       }
     }
     case ts.SyntaxKind.ArrayType: {
-      const arrNode = typeNode as ts.ArrayTypeNode;
+      const arrNode =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ typeNode as ts.ArrayTypeNode;
       return {
         t: "array",
         elementsType: resolveTypeNode(arrNode.elementType),
       };
     }
     case ts.SyntaxKind.TypeLiteral: {
-      const literalNode = typeNode as ts.TypeLiteralNode;
+      const literalNode =
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ typeNode as ts.TypeLiteralNode;
       return {
         t: "object",
         props: literalNode.members.map((member) => {
           if (ts.isIndexSignatureDeclaration(member)) {
             assert(member.parameters[0]);
             const res = resolveParamDec({
-              name: member.parameters[0].name as ts.Identifier,
-              type: member.parameters[0].type as ts.TypeNode,
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ member
+                .parameters[0].name as ts.Identifier,
+              type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ member
+                .parameters[0].type as ts.TypeNode,
             });
 
             return resolveParamDec({
-              name: {
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ {
                 escapedText: `[${res.name}${res.optional ? "?" : ""}: ${res.type}]`,
               } as ts.Identifier,
               type: member.type,
             });
           } else {
             return resolveParamDec({
-              name: (member as ts.PropertySignature).name as ts.Identifier,
-              type: (member as ts.PropertySignature).type as ts.TypeNode,
-              optional: (member as ts.PropertySignature).questionToken !== undefined,
+              name: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                member as ts.PropertySignature
+              ).name as ts.Identifier,
+              type: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                member as ts.PropertySignature
+              ).type as ts.TypeNode,
+              optional:
+                /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+                  member as ts.PropertySignature
+                ).questionToken !== undefined,
             });
           }
         }),
@@ -315,26 +329,40 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.TypeReference:
       return {
         t: "ref",
-        id: ((typeNode as ts.TypeReferenceNode).typeName as ts.Identifier).escapedText.toString(),
-        args: (typeNode as ts.TypeReferenceNode).typeArguments?.map((typeArg) =>
-          resolveTypeNode(typeArg),
-        ),
+        id: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          (typeNode as ts.TypeReferenceNode).typeName as ts.Identifier
+        ).escapedText.toString(),
+        args: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.TypeReferenceNode
+        ).typeArguments?.map((typeArg) => resolveTypeNode(typeArg)),
       };
     case ts.SyntaxKind.UnionType:
       return {
         t: "union",
-        types: (typeNode as ts.UnionTypeNode).types.map((type) => resolveTypeNode(type)),
+        types: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.UnionTypeNode
+        ).types.map((type) => resolveTypeNode(type)),
       };
     case ts.SyntaxKind.IntersectionType:
       return {
         t: "intersection",
-        types: (typeNode as ts.IntersectionTypeNode).types.map((type) => resolveTypeNode(type)),
+        types: /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.IntersectionTypeNode
+        ).types.map((type) => resolveTypeNode(type)),
       };
     case ts.SyntaxKind.IndexedAccessType:
       return {
         t: "indexed-access",
-        object: resolveTypeNode((typeNode as ts.IndexedAccessTypeNode).objectType),
-        index: resolveTypeNode((typeNode as ts.IndexedAccessTypeNode).indexType),
+        object: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.IndexedAccessTypeNode
+          ).objectType,
+        ),
+        index: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.IndexedAccessTypeNode
+          ).indexType,
+        ),
       };
     case ts.SyntaxKind.TupleType:
       if (ts.isTupleTypeNode(typeNode)) {
@@ -347,18 +375,29 @@ function resolveTypeNode(typeNode: ts.TypeNode): ApiParamType {
     case ts.SyntaxKind.ParenthesizedType:
       // 괄호로 묶인 타입 (예: (A & B)[] 에서 (A & B))
       // 내부 타입을 재귀적으로 resolve
-      return resolveTypeNode((typeNode as ts.ParenthesizedTypeNode).type);
+      return resolveTypeNode(
+        /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+          typeNode as ts.ParenthesizedTypeNode
+        ).type,
+      );
 
     case ts.SyntaxKind.FunctionType:
       return {
         t: "function",
-        parameters: (typeNode as ts.FunctionTypeNode).parameters.map((param) => ({
-          name: param.name.getText(),
-          type: param.type ? resolveTypeNode(param.type) : "unknown",
-          optional: param.questionToken !== undefined,
-          defaultDef: undefined,
-        })),
-        returnType: resolveTypeNode((typeNode as ts.FunctionTypeNode).type),
+        parameters:
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.FunctionTypeNode
+          ).parameters.map((param) => ({
+            name: param.name.getText(),
+            type: param.type ? resolveTypeNode(param.type) : "unknown",
+            optional: param.questionToken !== undefined,
+            defaultDef: undefined,
+          })),
+        returnType: resolveTypeNode(
+          /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ (
+            typeNode as ts.FunctionTypeNode
+          ).type,
+        ),
       };
     case undefined:
       throw new Error(`typeNode undefined`);
@@ -377,7 +416,8 @@ function resolveParamDec(
   },
   index: number = 0,
 ): ApiParam {
-  const name = paramDec.name as ts.Identifier;
+  const name =
+    /* SAFETY: TypeScript AST 파싱과 동기화 입력 계약이 이 값의 타입을 보장한다. */ paramDec.name as ts.Identifier;
   const type = resolveTypeNode(paramDec.type);
 
   if (name === undefined) {