sonamu 0.10.12 → 0.10.13

package/src/ui/async-route.ts

@@ -0,0 +1,4 @@
+/** Fastify가 비동기 실패를 오류 처리기로 전달할 수 있도록 Promise를 반환합니다. */
+export function forwardAsyncErrors<Result>(handler: () => Promise<Result>): Promise<Result> {
+  return Promise.resolve().then(handler);
+}

package/src/ui/cdd-service.ts

@@ -4,6 +4,7 @@ import os from "os";
 import path from "path";
 
 import { Sonamu } from "../api/sonamu";
+import { isStringValue } from "../utils/runtime-value";
 import {
   type CddAcEntry,
   type CddAcFile,
@@ -17,6 +18,22 @@ import {
   type CddTreeNode,
 } from "./cdd-types";
 
+interface CddTreeResult {
+  exists: boolean;
+  tree: CddTreeNode[];
+}
+interface EditorCliConfig {
+  cli: string;
+  waitFlag: string;
+}
+interface EditorCliResolution {
+  bin: string;
+  args: string[];
+}
+interface CddRulesResult {
+  rules: CddRuleSummary[];
+}
+
 export type {
   CddAcEntry,
   CddAcFile,
@@ -93,7 +110,7 @@ function scanDirectory(dirPath: string, relativeTo: string): CddTreeNode[] {
 }
 
 /** contract/ 디렉터리의 트리 구조를 반환 */
-export function getCddTree(): { exists: boolean; tree: CddTreeNode[] } {
+export function getCddTree(): CddTreeResult {
   const contractDir = getContractDir();
   if (!fs.existsSync(contractDir)) {
     return { exists: false, tree: [] };
@@ -142,17 +159,17 @@ export async function editContent(
 }
 
 /** 에디터별 앱 번들 내 CLI 경로 + --wait 플래그 매핑 */
-const EDITOR_CLI_MAP: Record<string, { cli: string; waitFlag: string }> = {
+const EDITOR_CLI_MAP = {
   "Visual Studio Code": { cli: "Contents/Resources/app/bin/code", waitFlag: "--wait" },
   Zed: { cli: "Contents/MacOS/cli", waitFlag: "--wait" },
   Cursor: { cli: "Contents/Resources/app/bin/cursor", waitFlag: "--wait" },
-};
+} satisfies Record<string, EditorCliConfig>;
 
 /** 앱 번들 CLI 경로를 resolve. wait=false이면 --wait 플래그를 생략 */
-function resolveEditorCli(options?: { wait?: boolean }): { bin: string; args: string[] } {
+function resolveEditorCli(options?: { wait?: boolean }): EditorCliResolution {
   const wait = options?.wait ?? true;
   const appName = Sonamu.config.externalEditor ?? "Visual Studio Code";
-  const mapping = EDITOR_CLI_MAP[appName];
+  const mapping = Object.entries(EDITOR_CLI_MAP).find(([name]) => name === appName)?.[1];
   if (!mapping) {
     throw new Error(
       `지원되지 않는 에디터입니다: ${appName} (지원: ${Object.keys(EDITOR_CLI_MAP).join(", ")})`,
@@ -218,7 +235,7 @@ export function openSourceFile(filePath: string): void {
  * ======================================================================== */
 
 /** contract/rules/ 디렉터리 내 .rules.json 파일 목록 반환 */
-export function listRules(): { rules: CddRuleSummary[] } {
+export function listRules(): CddRulesResult {
   const contractDir = getContractDir();
   const rulesDir = path.join(contractDir, "rules");
   if (!fs.existsSync(rulesDir)) return { rules: [] };
@@ -235,11 +252,13 @@ export function listRules(): { rules: CddRuleSummary[] } {
 
     try {
       const raw = fs.readFileSync(absPath, "utf-8");
-      const doc = JSON.parse(raw) as { description?: string; rules?: unknown[] };
+      const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+        raw,
+      ) as { description?: string; rules?: unknown[] };
       rules.push({
         key,
         path: relPath,
-        description: typeof doc.description === "string" ? doc.description : "",
+        description: isStringValue(doc.description) ? doc.description : "",
         ruleCount: Array.isArray(doc.rules) ? doc.rules.length : 0,
       });
     } catch (err) {
@@ -266,12 +285,14 @@ export function readRule(ruleKey: string): CddRuleDetail {
   }
 
   const raw = fs.readFileSync(absPath, "utf-8");
-  const doc = JSON.parse(raw) as { description?: string; rules?: CddRuleEntry[] };
+  const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+    raw,
+  ) as { description?: string; rules?: CddRuleEntry[] };
 
   return {
     key: ruleKey,
     path: `rules/${ruleKey}.rules.json`,
-    description: typeof doc.description === "string" ? doc.description : "",
+    description: isStringValue(doc.description) ? doc.description : "",
     rules: Array.isArray(doc.rules) ? doc.rules : [],
   };
 }
@@ -287,7 +308,9 @@ export function addRule(req: CddAddRuleRequest): CddRuleDetail {
   }
 
   const raw = fs.readFileSync(absPath, "utf-8");
-  const doc = JSON.parse(raw) as { description?: string; rules?: CddRuleEntry[] };
+  const doc = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ JSON.parse(
+    raw,
+  ) as { description?: string; rules?: CddRuleEntry[] };
   const rules: CddRuleEntry[] = Array.isArray(doc.rules) ? doc.rules : [];
 
   const nextId = generateNextRuleId(rules);
@@ -308,7 +331,7 @@ export function addRule(req: CddAddRuleRequest): CddRuleDetail {
   return {
     key: req.ruleKey,
     path: `rules/${req.ruleKey}.rules.json`,
-    description: typeof doc.description === "string" ? doc.description : "",
+    description: isStringValue(doc.description) ? doc.description : "",
     rules,
   };
 }

package/src/ui/migrations-api.ts

@@ -20,6 +20,7 @@ import {
   type MigrationStreamEvent,
   type MigrationTarget,
 } from "../migration/types";
+import { forwardAsyncErrors } from "./async-route";
 
 type ApprovalReady = { type: "ready" };
 type ApprovalResult = ApprovalReady | SlackConfirmPendingResult;
@@ -39,7 +40,8 @@ function assertTargets(migrator: Migrator, targets: MigrationTarget[]): void {
 }
 
 function targetRequiresApproval(slack: SlackConfirm, target: MigrationTarget): boolean {
-  const connection = Sonamu.dbConfig[target]?.connection as { host?: string } | undefined;
+  const connection = /* SAFETY: UI 도구의 Zod 입력 스키마가 이 값의 타입을 보장한다. */ Sonamu
+    .dbConfig[target]?.connection as { host?: string } | undefined;
   const remote = !LOCAL_HOSTS.has((connection?.host ?? "localhost").toLowerCase());
   return remote && slack.isTargetRequiresApproval(target);
 }
@@ -251,58 +253,65 @@ export async function registerMigrationsApi(server: FastifyInstance) {
     connections: migrator.getConnections(),
   }));
   server.get("/api/migrations/codes", async () => ({ codes: await migrator.getMigrationCodes() }));
-  server.get<{ Querystring: { codeName: string } }>("/api/migrations/code", async (request) => {
-    const migrationCode = (await migrator.getMigrationCodes()).find(
-      ({ name }) => name === request.query.codeName,
-    );
-    if (migrationCode === undefined) {
-      throw new BadRequestException(SD("error.badRequest"));
-    }
-    return { code: await readFile(migrationCode.path, "utf8") };
-  });
-  server.get<{ Querystring: { connKey?: MigrationTarget } }>(
-    "/api/migrations/status",
-    async (request) => {
+  server.get<{ Querystring: { codeName: string } }>("/api/migrations/code", (request) =>
+    forwardAsyncErrors(async () => {
+      const migrationCode = (await migrator.getMigrationCodes()).find(
+        ({ name }) => name === request.query.codeName,
+      );
+      if (migrationCode === undefined) {
+        throw new BadRequestException(SD("error.badRequest"));
+      }
+      return { code: await readFile(migrationCode.path, "utf8") };
+    }),
+  );
+  server.get<{ Querystring: { connKey?: MigrationTarget } }>("/api/migrations/status", (request) =>
+    forwardAsyncErrors(async () => {
       if (request.query.connKey === undefined) {
         return { status: await migrator.getStatus() };
       }
       return { status: await migrator.getConnectionStatus(request.query.connKey) };
-    },
+    }),
   );
   server.get<{ Querystring: { compareConnKey: MigrationTarget } }>(
     "/api/migrations/prepared-codes",
-    async (request) => ({
-      preparedCodes: await migrator.getPreparedCodes(request.query.compareConnKey),
-    }),
+    (request) =>
+      forwardAsyncErrors(async () => ({
+        preparedCodes: await migrator.getPreparedCodes(request.query.compareConnKey),
+      })),
   );
 
-  server.post<{ Body: ApplyBody }>("/api/migrations/request-approval", async (request) => {
-    return requestApproval(migrator, request.body.targets, request.body.requestor);
-  });
+  server.post<{ Body: ApplyBody }>("/api/migrations/request-approval", (request) =>
+    forwardAsyncErrors(async () => {
+      return requestApproval(migrator, request.body.targets, request.body.requestor);
+    }),
+  );
   server.post<{ Body: { channel: string; ts: string } }>(
     "/api/migrations/checkApproval",
-    async (request) => {
-      const slack = new SlackConfirm();
-      return slack.isConfigured()
-        ? slack.checkApproval(request.body.channel, request.body.ts)
-        : { approved: true, rejected: false };
-    },
+    (request) =>
+      forwardAsyncErrors(async () => {
+        const slack = new SlackConfirm();
+        return slack.isConfigured()
+          ? slack.checkApproval(request.body.channel, request.body.ts)
+          : { approved: true, rejected: false };
+      }),
   );
   server.post<{
     Body: { channel: string; ts: string; reason: string; requestor?: string };
-  }>("/api/migrations/forceApproval", async (request) => {
-    const slack = new SlackConfirm();
-    if (!slack.isConfigured()) {
-      throw new BadRequestException(SD("sonamu.error.slackConfirmNotConfigured"));
-    }
-    await slack.forceApproval(
-      request.body.channel,
-      request.body.ts,
-      request.body.reason,
-      request.body.requestor,
-    );
-    return { success: true };
-  });
+  }>("/api/migrations/forceApproval", (request) =>
+    forwardAsyncErrors(async () => {
+      const slack = new SlackConfirm();
+      if (!slack.isConfigured()) {
+        throw new BadRequestException(SD("sonamu.error.slackConfirmNotConfigured"));
+      }
+      await slack.forceApproval(
+        request.body.channel,
+        request.body.ts,
+        request.body.reason,
+        request.body.requestor,
+      );
+      return { success: true };
+    }),
+  );
 
   server.post("/api/migrations/shadow", async (_request, reply) => {
     return sendMigrationStream(reply, "shadow", [], (onProgress) => {
@@ -343,7 +352,8 @@ export async function registerMigrationsApi(server: FastifyInstance) {
 
   server.post<{ Body: { compareConnKey?: MigrationTarget } }>(
     "/api/migrations/generatePreparedCodes",
-    async (request) => migrator.generatePreparedCodes(request.body.compareConnKey),
+    (request) =>
+      forwardAsyncErrors(async () => migrator.generatePreparedCodes(request.body.compareConnKey)),
   );
 
   // 이전 UI 번들과 외부 스크립트가 새 서버에서도 한 릴리스 동안 동작하도록 유지합니다.
@@ -355,15 +365,17 @@ export async function registerMigrationsApi(server: FastifyInstance) {
       forceReason?: string;
       requestor?: string;
     };
-  }>("/api/migrations/runAction", async (request) => {
-    if (request.body.action === "shadow") {
-      return migrator.runShadowTest();
-    }
-    if (request.body.action === "apply") {
-      return runLegacyApply(migrator, request.body);
-    }
-    assertTargets(migrator, request.body.targets);
-    await getAvailableTargetStatuses(migrator, request.body.targets);
-    return migrator.rollback(request.body.targets);
-  });
+  }>("/api/migrations/runAction", (request) =>
+    forwardAsyncErrors(async () => {
+      if (request.body.action === "shadow") {
+        return migrator.runShadowTest();
+      }
+      if (request.body.action === "apply") {
+        return runLegacyApply(migrator, request.body);
+      }
+      assertTargets(migrator, request.body.targets);
+      await getAvailableTargetStatuses(migrator, request.body.targets);
+      return migrator.rollback(request.body.targets);
+    }),
+  );
 }

package/src/utils/formatter.ts

@@ -10,8 +10,9 @@ import { format, type FormatConfig } from "oxfmt";
 import { cached } from "./async-utils";
 import { isTest } from "./controller";
 import { execute } from "./process-utils";
+import { isNumberValue } from "./runtime-value";
 
-const _require = createRequire(import.meta.url);
+const requireFromHere = createRequire(import.meta.url);
 
 /**
  * 코드를 프로젝트의 oxfmt + oxlint 설정에 맞춰 포매팅한 문자열을 반환합니다.
@@ -75,9 +76,11 @@ async function loadOxfmtConfig(): Promise<FormatConfig> {
   while (true) {
     const candidate = join(dir, ".oxfmtrc.json");
     try {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
       cachedOxfmtConfig = JSON.parse(await readFile(candidate, "utf-8")) as FormatConfig;
       return cachedOxfmtConfig;
     } catch (e) {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
       if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
         !isTest() && console.error(`Failed to load ${candidate}:`, e);
         break;
@@ -121,7 +124,8 @@ async function runOxlint(code: string): Promise<string> {
       });
     } catch (e) {
       // lint 위반 시 exit code != 0이지만 --fix는 적용됨. exec 자체 실패만 throw.
-      if (typeof (e as Error & { code?: number }).code !== "number") {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
+      if (!isNumberValue((e as Error & { code?: number }).code)) {
         throw e;
       }
     }
@@ -138,7 +142,7 @@ async function runOxlint(code: string): Promise<string> {
 
 function resolveOxlintBin(): string {
   try {
-    return _require.resolve("oxlint/bin/oxlint");
+    return requireFromHere.resolve("oxlint/bin/oxlint");
   } catch {
     return "oxlint";
   }

package/src/utils/fs-utils.ts

@@ -8,12 +8,12 @@ import { formatCode } from "./formatter";
 /**
  * fs/promises에는 exists가 없어요. 대신 access가 있습니다.
  * 근데 얘는 인터페이스가 쓰기 불편해요. 그래서 감싸주었습니다.
- * @param path
+ * @param targetPath
  * @returns
  */
-export async function exists(path: PathLike): Promise<boolean> {
+export async function exists(targetPath: PathLike): Promise<boolean> {
   try {
-    await access(path, constants.F_OK);
+    await access(targetPath, constants.F_OK);
     return true;
   } catch {
     return false;
@@ -21,9 +21,9 @@ export async function exists(path: PathLike): Promise<boolean> {
 }
 
 // 디렉토리가 아니라 파일만 존재하는지 확인합니다.
-export async function fileExists(path: PathLike): Promise<boolean> {
+export async function fileExists(targetPath: PathLike): Promise<boolean> {
   try {
-    const stats = await stat(path);
+    const stats = await stat(targetPath);
     return stats.isFile();
   } catch {
     return false;

package/src/utils/model.ts

@@ -1,9 +1,7 @@
-import { type SonamuQueryMode } from "../types/types";
+import { type SonamuQueryMode, type SonamuSemanticParams } from "../types/types";
 
 // semanticQuery가 있으면 similarity를 추가하는 조건부 타입
-type WithSimilarity<LP, T> = LP extends { semanticQuery: Record<string, unknown> }
-  ? T & { similarity: number }
-  : T;
+type WithSimilarity<LP, T> = "semanticQuery" extends keyof LP ? T & { similarity: number } : T;
 
 export type ListResult<
   LP extends { queryMode?: SonamuQueryMode },
@@ -20,6 +18,7 @@ export function asArray<T>(param: T | T[]): T[] {
   if (Array.isArray(param)) {
     return param;
   } else {
+    // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
     return [param] as T[];
   }
 }
@@ -39,5 +38,5 @@ export interface BaseListParams {
   page?: number;
   keyword?: string;
   queryMode?: "list" | "count" | "both";
-  semanticQuery?: Record<string, unknown>;
+  semanticQuery?: SonamuSemanticParams["semanticQuery"];
 }

package/src/utils/object-utils.ts

@@ -1,3 +1,12 @@
+import {
+  isBigIntValue,
+  isFunctionValue,
+  isNumberValue,
+  isObjectValue,
+  isStringValue,
+  isSymbolValue,
+} from "./runtime-value";
+
 type Primitive = string | number | boolean | null | undefined;
 
 type TypedArray =
@@ -84,8 +93,8 @@ export interface SerializableCheckResult {
  * isSerializable({ fn: () => {} }) // { valid: false, reason: "Function at fn" }
  * isSerializable({ deep: { nested: Promise.resolve() } }) // { valid: false, reason: "Promise at deep.nested" }
  */
-export function isSerializable(
-  value: unknown,
+export function isSerializable<Value>(
+  value: Value,
   path: string[] = [],
   seen: WeakSet<object> = new WeakSet(),
 ): SerializableCheckResult {
@@ -94,23 +103,26 @@ export function isSerializable(
     return { valid: true };
   }
 
-  const type = typeof value;
-  if (type === "string" || type === "number" || type === "boolean" || type === "undefined") {
-    return { valid: true };
-  }
-  if (type === "bigint") {
+  if (
+    isStringValue(value) ||
+    isNumberValue(value) ||
+    value === true ||
+    value === false ||
+    value === undefined ||
+    isBigIntValue(value)
+  ) {
     return { valid: true };
   }
 
-  if (type === "function") {
+  if (isFunctionValue(value)) {
     return { valid: false, reason: `Function at ${formatPath(path)}` };
   }
-  if (type === "symbol") {
+  if (isSymbolValue(value)) {
     return { valid: false, reason: `Symbol at ${formatPath(path)}` };
   }
 
-  if (type === "object") {
-    const obj = value as object;
+  if (isObjectValue(value)) {
+    const obj = value;
 
     if (obj instanceof Promise) {
       return { valid: false, reason: `Promise at ${formatPath(path)}` };
@@ -126,7 +138,7 @@ export function isSerializable(
     if (obj instanceof WeakSet) {
       return { valid: false, reason: `WeakSet at ${formatPath(path)}` };
     }
-    if (typeof WeakRef !== "undefined" && obj instanceof WeakRef) {
+    if ("WeakRef" in globalThis && obj instanceof WeakRef) {
       return { valid: false, reason: `WeakRef at ${formatPath(path)}` };
     }
 
@@ -179,13 +191,11 @@ export function isSerializable(
 
     // Vitest는 Error를 허용하지만 속성은 직렬화 필요
     if (obj instanceof Error) {
-      const errorProps = Object.keys(obj).filter((k) => !["name", "message", "stack"].includes(k));
-      for (const key of errorProps) {
-        const result = isSerializable(
-          (obj as unknown as Record<string, unknown>)[key],
-          [...path, key],
-          seen,
-        );
+      const errorEntries = Object.entries(obj).filter(
+        ([key]) => !["name", "message", "stack"].includes(key),
+      );
+      for (const [key, nestedValue] of errorEntries) {
+        const result = isSerializable(nestedValue, [...path, key], seen);
         if (!result.valid) return result;
       }
       return { valid: true };
@@ -201,14 +211,14 @@ export function isSerializable(
       };
     }
 
-    for (const key of Object.keys(obj)) {
-      const result = isSerializable((obj as Record<string, unknown>)[key], [...path, key], seen);
+    for (const [key, nestedValue] of Object.entries(obj)) {
+      const result = isSerializable(nestedValue, [...path, key], seen);
       if (!result.valid) return result;
     }
     return { valid: true };
   }
 
-  return { valid: false, reason: `Unknown type (${type}) at ${formatPath(path)}` };
+  return { valid: false, reason: `Unknown value at ${formatPath(path)}` };
 }
 
 function formatPath(path: string[]): string {

package/src/utils/process-utils.ts

@@ -4,6 +4,8 @@ import { promisify } from "util";
 
 import chalk from "chalk";
 
+import { isStringValue } from "./runtime-value";
+
 const execFileAsync = promisify(execFile);
 
 /**
@@ -16,7 +18,7 @@ export async function execute(
   options?: ExecFileOptions,
 ): Promise<string> {
   const { stdout } = await execFileAsync(bin, args, options);
-  return typeof stdout === "string" ? stdout : stdout.toString();
+  return isStringValue(stdout) ? stdout : stdout.toString();
 }
 
 /**
@@ -37,6 +39,7 @@ export async function runWithGracefulShutdown(
     waitForUpTo: 20000,
   },
 ): Promise<void> {
+  // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
   let isRunning = true as boolean;
 
   const abortController = new AbortController();

package/src/utils/runtime-value.ts

@@ -0,0 +1,43 @@
+function hasPrimitiveTag<Value>(value: Value, tag: string): boolean {
+  return Object.prototype.toString.call(value) === tag && Object(value) !== value;
+}
+
+/** 런타임 값이 원시 문자열인지 판별합니다. */
+export function isStringValue<Value>(value: Value): value is Value & string {
+  return hasPrimitiveTag(value, "[object String]");
+}
+
+/** 런타임 값이 원시 숫자인지 판별합니다. */
+export function isNumberValue<Value>(value: Value): value is Value & number {
+  return hasPrimitiveTag(value, "[object Number]");
+}
+
+/** 런타임 값이 원시 심벌인지 판별합니다. */
+export function isSymbolValue<Value>(value: Value): value is Value & symbol {
+  return hasPrimitiveTag(value, "[object Symbol]");
+}
+
+/** 런타임 값이 원시 bigint인지 판별합니다. */
+export function isBigIntValue<Value>(value: Value): value is Value & bigint {
+  return hasPrimitiveTag(value, "[object BigInt]");
+}
+
+/** 런타임 값이 함수인지 판별합니다. */
+export function isFunctionValue<Value>(value: Value): value is Value & CallableFunction {
+  try {
+    const tag = Object.prototype.toString.call(value);
+    return (
+      tag === "[object Function]" ||
+      tag === "[object AsyncFunction]" ||
+      tag === "[object GeneratorFunction]" ||
+      tag === "[object AsyncGeneratorFunction]"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** null과 함수를 제외한 객체 표현인지 판별합니다. */
+export function isObjectValue<Value>(value: Value): value is Value & object {
+  return value !== null && Object(value) === value && !isFunctionValue(value);
+}

package/src/utils/sql-parser.ts

@@ -9,15 +9,21 @@ import {
 } from "node-sql-parser";
 import { unique } from "radashi";
 
+import { isObjectValue, isStringValue } from "./runtime-value";
 import { nonNullable } from "./utils";
 
-export function getTableName(expr: ColumnRef) {
-  if ("table" in expr && expr.table !== null) {
-    return typeof expr.table === "string"
-      ? expr.table
-      : (expr.table as { type: string; value: string }).value;
+type ParserColumnRef = Omit<ColumnRef, "table"> & {
+  table?: string | { type: string; value: string } | null;
+};
+
+export function getTableName(expr: ParserColumnRef) {
+  const table = expr.table;
+  if (isStringValue(table)) {
+    return table;
   }
-  return null;
+  return isObjectValue(table) && "value" in table && isStringValue(table.value)
+    ? table.value
+    : null;
 }
 
 // where 조건에 사용된 테이블명을 추출
@@ -29,6 +35,7 @@ export function getTableNamesFromWhere(ast: AST | AST[]): string[] {
 
     const extractTableName = (expr: Expr | ExpressionValue): string[] => {
       if (expr.type === "column_ref") {
+        // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
         const table = getTableName(expr as ColumnRef);
         return table ? [table] : [];
       } else if (expr.type === "binary_expr" && "left" in expr) {

package/src/utils/type-utils.ts

@@ -1,3 +1,4 @@
+import { isObjectValue } from "./runtime-value";
 // 타입을 펼쳐서 보여주는 유틸리티 (객체에만 사용해야 함)
 type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
 
@@ -32,9 +33,9 @@ export function withProp<T extends object, P extends string, V>(
   const result = structuredClone(obj);
 
   // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 범용 배열 요소 타입
-  const setDeep = (current: any, keys: string[], value: V): void => {
-    if (keys.length === 0) return;
-    const [key, ...rest] = keys;
+  const setDeep = (current: any, pathKeys: string[]): void => {
+    if (pathKeys.length === 0) return;
+    const [key, ...rest] = pathKeys;
 
     if (rest.length === 0) {
       if (Array.isArray(current)) {
@@ -45,21 +46,22 @@ export function withProp<T extends object, P extends string, V>(
         current[key] = value;
       }
     } else {
-      if (!(key in current) || typeof current[key] !== "object") {
+      if (!(key in current) || !isObjectValue(current[key])) {
         current[key] = {};
       }
       if (Array.isArray(current[key])) {
         // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 범용 배열 요소 타입
         current[key].forEach((item: any) => {
-          setDeep(item, rest, value);
+          setDeep(item, rest);
         });
       } else {
-        setDeep(current[key], rest, value);
+        setDeep(current[key], rest);
       }
     }
   };
 
-  setDeep(result, keys, value);
+  setDeep(result, keys);
+  // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
   return result as SetPath<T, P, V>;
 }