@cartanova/qgrid-cli 2.10.10 → 2.11.1

package/bundle/src/application/qgrid/tool-emulation-schema.ts

@@ -11,6 +11,8 @@
  *   → "Composing Tools With A User Output Schema"
  */
 
+import { z } from "zod";
+
 import {
   SCHEMA_ARRAY_KEYWORDS,
   SCHEMA_DEPENDENCIES_KEYWORD,
@@ -18,7 +20,11 @@ import {
   SCHEMA_SINGLE_KEYWORDS,
   UNSUPPORTED_REFERENCE_KEYWORDS,
 } from "../../utils/providers/common/json-schema-keywords";
-import { type JsonValue } from "../../utils/providers/common/provider-types";
+import {
+  isJsonObject,
+  type JsonObject,
+  type JsonValue,
+} from "../../utils/providers/common/provider-types";
 import { type QgridTool } from "./qgrid.types";
 
 const USER_OUTPUT_DEFINITION = "__qgrid_user_output";
@@ -44,6 +50,7 @@ export function buildToolCallSchema(tools: QgridTool[], answerSchema?: JsonValue
   const toolDescriptions = tools
     .map((tool) => {
       const schema = JSON.stringify(tool.inputSchema);
+
       return `- ${tool.name}: ${tool.description ?? ""}\n  inputSchema: ${schema}`;
     })
     .join("\n");
@@ -51,7 +58,7 @@ export function buildToolCallSchema(tools: QgridTool[], answerSchema?: JsonValue
   const normalizedAnswerSchema =
     answerSchema === undefined ? undefined : rebaseUserOutputSchema(answerSchema);
 
-  return {
+  const envelope: JsonObject = {
     type: "object",
     description:
       "Return exactly one JSON object matching this schema as your final response, including when requesting a tool. This object is the response body, not a call to a built-in tool. To request client-side tools, set result.action to tool_call and include result.toolCalls, then end your turn. The client executes those tools and supplies their results in a later request. Do not invent tool results or emit an answer before receiving the required results.",
@@ -108,29 +115,28 @@ export function buildToolCallSchema(tools: QgridTool[], answerSchema?: JsonValue
     },
     required: ["result"],
     additionalProperties: false,
-    ...(normalizedAnswerSchema === undefined
-      ? {}
-      : {
-          $defs: {
-            [USER_OUTPUT_DEFINITION]: normalizedAnswerSchema,
-          },
-        }),
   };
+
+  if (normalizedAnswerSchema !== undefined) {
+    envelope.$defs = { [USER_OUTPUT_DEFINITION]: normalizedAnswerSchema };
+  }
+
+  return envelope;
 }
 
 function rebaseUserOutputSchema(schema: JsonValue): JsonValue {
-  return rewriteSchemaNode(schema, "$");
+  return rewriteSchemaNode(schema, "$") ?? schema;
 }
 
 const MAP_KEYWORDS = new Set<string>(SCHEMA_MAP_KEYWORDS);
 const ARRAY_KEYWORDS = new Set<string>(SCHEMA_ARRAY_KEYWORDS);
 const SINGLE_KEYWORDS = new Set<string>(SCHEMA_SINGLE_KEYWORDS);
 
-function rewriteSchemaNode(value: JsonValue, path: string): JsonValue {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+function rewriteSchemaNode(value: JsonValue | undefined, path: string): JsonValue | undefined {
+  if (!isJsonObject(value)) return value;
 
-  const source = value as Record<string, JsonValue>;
-  const result: Record<string, JsonValue> = { ...source };
+  const source = value;
+  const result: JsonObject = { ...source };
 
   for (const unsupportedKeyword of UNSUPPORTED_REFERENCE_KEYWORDS) {
     if (Object.hasOwn(source, unsupportedKeyword)) {
@@ -142,13 +148,15 @@ function rewriteSchemaNode(value: JsonValue, path: string): JsonValue {
   }
 
   if ("$ref" in source) {
-    const ref = source.$ref;
-    if (typeof ref !== "string" || (ref !== "#" && !ref.startsWith("#/"))) {
+    const ref = z.string().safeParse(source.$ref).data;
+
+    if (ref === undefined || (ref !== "#" && !ref.startsWith("#/"))) {
       throw new ToolSchemaCompositionError(
         "only root-relative JSON Pointer $ref values are supported",
         `${path}.$ref`,
       );
     }
+
     result.$ref = `${USER_OUTPUT_REF}${ref.slice(1)}`;
   }
 
@@ -161,7 +169,7 @@ function rewriteSchemaNode(value: JsonValue, path: string): JsonValue {
           name,
           rewriteSchemaNode(schema, `${keywordPath}.${name}`),
         ]),
-      ) as JsonValue;
+      );
     } else if (keyword === SCHEMA_DEPENDENCIES_KEYWORD && isJsonObject(child)) {
       result[keyword] = Object.fromEntries(
         Object.entries(child).map(([name, dependency]) => [
@@ -170,25 +178,21 @@ function rewriteSchemaNode(value: JsonValue, path: string): JsonValue {
             ? dependency
             : rewriteSchemaNode(dependency, `${keywordPath}.${name}`),
         ]),
-      ) as JsonValue;
+      );
     } else if (ARRAY_KEYWORDS.has(keyword) && Array.isArray(child)) {
-      result[keyword] = child.map((schema, index) =>
-        rewriteSchemaNode(schema, `${keywordPath}[${index}]`),
-      ) as JsonValue;
+      result[keyword] = child.map(
+        (schema, index) => rewriteSchemaNode(schema, `${keywordPath}[${index}]`) ?? schema,
+      );
     } else if (SINGLE_KEYWORDS.has(keyword)) {
       if (keyword === "items" && Array.isArray(child)) {
-        result[keyword] = child.map((schema, index) =>
-          rewriteSchemaNode(schema, `${keywordPath}[${index}]`),
-        ) as JsonValue;
+        result[keyword] = child.map(
+          (schema, index) => rewriteSchemaNode(schema, `${keywordPath}[${index}]`) ?? schema,
+        );
       } else {
         result[keyword] = rewriteSchemaNode(child, keywordPath);
       }
     }
   }
 
-  return result as JsonValue;
-}
-
-function isJsonObject(value: JsonValue): value is Record<string, JsonValue> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
+  return result;
 }

package/bundle/src/application/qgrid/tool-emulation.ts

@@ -3,6 +3,8 @@ import { Buffer } from "node:buffer";
 import { getLogger } from "@logtape/logtape";
 import { z } from "zod";
 
+import { type JsonValue } from "../../utils/providers/common/provider-types";
+
 // 응답(모델 출력) envelope 의 자원 한도. caller 스키마 전처리 한도(CALLER_SCHEMA_LIMITS)와 값이
 // 같아 보여도 서로 다른 자원을 지키는 독립 상수다 — 스키마 깊이는 인스턴스 깊이를 bound 하지
 // 않으므로(재귀 $ref 허용) 캘러 한도를 조정해도 응답 수용 기준이 따라 움직여선 안 된다.
@@ -11,6 +13,7 @@ const STRUCTURED_ENVELOPE_LIMITS = {
   maxNodes: 20_000,
   maxDepth: 132,
 } as const;
+
 import {
   type ImageGenerationMetadata,
   type QgridContent,
@@ -22,6 +25,7 @@ import {
 const logger = getLogger(["qgrid", "tool-emulation"]);
 
 type EmulationResult = Omit<QueryOutput, "content" | "finishReason" | "runContext">;
+
 type ToolCall = { toolName: string; args: string };
 
 // envelope 는 {result: <union>} 한 겹 구조 — 스키마 근거는 tool-emulation-schema.ts 참조.
@@ -58,6 +62,7 @@ function buildEnvelopeSchema(answerKind: AnswerKind) {
 
 const TEXT_ENVELOPE = buildEnvelopeSchema("text");
 const JSON_ENVELOPE = buildEnvelopeSchema("json");
+
 type EnvelopeResponse = z.infer<typeof JSON_ENVELOPE>["result"];
 
 export class ToolCallEmulationError extends Error {
@@ -99,18 +104,23 @@ export function applyToolCallEmulation(
   }
 
   const parsed = parseEnvelope(result.text, tools, answerKind);
+
   if (parsed.action === "tool_call") {
     return toolCallOutput(result, parsed.toolCalls, images, runContext);
   }
 
   return answerOutput(
     result,
-    answerKind === "text" ? (parsed.answer as string) : JSON.stringify(parsed.answer),
+    answerKind === "text" ? z.string().parse(parsed.answer) : JSON.stringify(parsed.answer),
     images,
     runContext,
   );
 }
 
+const commentaryToolCallControl = z.looseObject({
+  result: z.looseObject({ action: z.literal("tool_call") }),
+});
+
 export function isToolCallEnvelope(
   text: string,
   tools: QgridTool[],
@@ -120,23 +130,17 @@ export function isToolCallEnvelope(
   if (phase === "commentary") {
     // Commentary is not the structured answer. Only an explicit tool control
     // object is eligible, and that object must still pass the strict parser.
-    let value: unknown;
+    let value: JsonValue;
+
     try {
       value = JSON.parse(text);
     } catch {
       return false;
     }
-    if (
-      !value ||
-      typeof value !== "object" ||
-      !("result" in value) ||
-      !value.result ||
-      typeof value.result !== "object" ||
-      !("action" in value.result) ||
-      value.result.action !== "tool_call"
-    )
-      return false;
+
+    if (!commentaryToolCallControl.safeParse(value).success) return false;
   }
+
   return parseEnvelope(text, tools, answerKind).action === "tool_call";
 }
 
@@ -147,7 +151,9 @@ function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind)
     );
   }
 
-  let value: unknown;
+  // JSON.parse without a reviver yields only JSON values.
+  let value: JsonValue;
+
   try {
     value = JSON.parse(text);
   } catch (error) {
@@ -159,15 +165,18 @@ function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind)
     // 진단에는 위반 원문의 머리가 필요하다(SON-495 전례) — parse 에러 위치만으로는
     // "프로즈로 답했는지 / 펜스가 남았는지 / JSON 이 잘렸는지"를 구분할 수 없다.
     const head = JSON.stringify(text.slice(0, 200));
-    logger.warn(`tool envelope parse failed: ${(error as Error).message}; head=${head}`);
+    logger.warn(
+      `tool envelope parse failed: ${error instanceof Error ? error.message : String(error)}; head=${head}`,
+    );
     throw new ToolCallEmulationError(
-      `invalid tool envelope (response is not JSON — the model ignored the envelope contract; retry is the caller's decision): ${(error as Error).message}; response head: ${head}`,
+      `invalid tool envelope (response is not JSON — the model ignored the envelope contract; retry is the caller's decision): ${error instanceof Error ? error.message : String(error)}; response head: ${head}`,
     );
   }
 
   assertStructuredEnvelopeComplexity(value);
   const schema = answerKind === "text" ? TEXT_ENVELOPE : JSON_ENVELOPE;
   const validation = schema.safeParse(value);
+
   if (!validation.success) {
     const issue = validation.error.issues[0];
     const path = issue && issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
@@ -181,15 +190,19 @@ function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind)
     );
   }
 
-  // Zod clones JSON objects and drops own "__proto__" keys. The parsed JSON is safe to return
-  // after validation and preserves the caller's exact structured value.
+  // SAFETY: schema.safeParse(value) succeeded above, so value matches { result: EnvelopeResponse }.
+  // Zod clones JSON objects and drops own "__proto__" keys, so the validated raw value is returned
+  // to preserve the caller's exact structured answer.
   const response = (value as { result: EnvelopeResponse }).result;
+
   if (response.action === "tool_call") {
     const unknownTool = findUnknownTool(response.toolCalls, tools);
+
     if (unknownTool !== undefined) {
       throw new ToolCallEmulationError(`unknown emulated tool: ${unknownTool}`);
     }
   }
+
   return response;
 }
 
@@ -232,47 +245,59 @@ function answerOutput(
 
 function findUnknownTool(toolCalls: ToolCall[], tools: QgridTool[]): string | undefined {
   const knownToolNames = new Set(tools.map((tool) => tool.name));
+
   return toolCalls.find((toolCall) => !knownToolNames.has(toolCall.toolName))?.toolName;
 }
 
 function appendImages(content: QgridContent[], images?: EmulationImage[]): QgridContent[] {
   if (!images?.length) return content;
+
   return [
     ...content,
-    ...images.map(
-      (image): QgridContent => ({
+    ...images.map((image): QgridContent => {
+      const part: Extract<QgridContent, { type: "image" }> = {
         type: "image",
         data: image.data,
-        ...(image.mediaType ? { mediaType: image.mediaType } : {}),
         revisedPrompt: image.revisedPrompt ?? null,
-        ...(image.generation ? { generation: image.generation } : {}),
-      }),
-    ),
+      };
+
+      if (image.mediaType) part.mediaType = image.mediaType;
+
+      if (image.generation) part.generation = image.generation;
+
+      return part;
+    }),
   ];
 }
 
-function assertStructuredEnvelopeComplexity(root: unknown): void {
+function assertStructuredEnvelopeComplexity(root: JsonValue): void {
   const maxDepth = STRUCTURED_ENVELOPE_LIMITS.maxDepth;
-  const stack = [{ value: root, depth: 0 }];
+  const stack: Array<{ value: JsonValue | undefined; depth: number }> = [{ value: root, depth: 0 }];
   let nodes = 0;
 
   while (stack.length > 0) {
     const current = stack.pop()!;
     nodes += 1;
+
     if (nodes > STRUCTURED_ENVELOPE_LIMITS.maxNodes) {
       throw new ToolCallEmulationError(
         `structured-output envelope exceeds node limit of ${STRUCTURED_ENVELOPE_LIMITS.maxNodes}`,
       );
     }
+
     if (current.depth > maxDepth) {
       throw new ToolCallEmulationError(
         `structured-output envelope exceeds depth limit of ${maxDepth}`,
       );
     }
-    if (typeof current.value === "number" && !Number.isFinite(current.value)) {
+
+    // JSON.parse turns out-of-range literals such as 1e999 into ±Infinity; it never yields NaN.
+    if (current.value === Infinity || current.value === -Infinity) {
       throw new ToolCallEmulationError("answer must be valid JSON");
     }
-    if (current.value === null || typeof current.value !== "object") continue;
+
+    // Only JSON arrays and objects are Object instances; primitives and null are leaves.
+    if (!(current.value instanceof Object)) continue;
 
     for (const value of Object.values(current.value)) {
       stack.push({ value, depth: current.depth + 1 });

package/bundle/src/application/request-log/json-schema-type-text.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import {
-  renderJsonSchemaZodShapeText,
+  renderJsonSchemaZodText,
   renderJsonSchemaTypeText,
   renderParsedJsonSchemaTypeText,
 } from "./json-schema-type-text";
@@ -133,10 +133,10 @@ describe("renderJsonSchemaTypeText", () => {
   });
 });
 
-describe("renderJsonSchemaZodShapeText", () => {
+describe("renderJsonSchemaZodText", () => {
   it("renders a compact object shape with required, optional, and default annotations", () => {
     expect(
-      renderJsonSchemaZodShapeText(
+      renderJsonSchemaZodText(
         {
           type: "object",
           properties: {
@@ -159,7 +159,7 @@ describe("renderJsonSchemaZodShapeText", () => {
 
   it("shortens long string enums with an inline remainder comment", () => {
     expect(
-      renderJsonSchemaZodShapeText(
+      renderJsonSchemaZodText(
         {
           type: "object",
           properties: {
@@ -180,7 +180,7 @@ describe("renderJsonSchemaZodShapeText", () => {
 
   it("renders nested objects, arrays, unions, literals, and unknown nodes", () => {
     expect(
-      renderJsonSchemaZodShapeText({
+      renderJsonSchemaZodText({
         type: "object",
         properties: {
           filters: {

package/bundle/src/application/request-log/json-schema-type-text.ts

@@ -7,7 +7,13 @@
  * 모르는 키워드는 unknown 으로 접어 절대 던지지 않는다.
  */
 
-type SchemaNode = Record<string, unknown>;
+import { z } from "zod";
+
+import {
+  isJsonObject,
+  type JsonObject,
+  type JsonValue,
+} from "../../utils/providers/common/provider-types";
 
 /** TS/zod 표시 코드 공용 식별자 판별 — zod-code-format 의 키 unquote 도 이걸 쓴다. */
 export const IDENT_SOURCE = "[A-Za-z_$][\\w$]*";
@@ -17,90 +23,127 @@ function renderKey(key: string): string {
   return IDENT_RE.test(key) ? key : JSON.stringify(key);
 }
 
-function renderPrimitive(type: unknown): string {
+function renderPrimitive(type: JsonValue | undefined): string {
   if (type === "string") return "string";
+
   if (type === "number" || type === "integer") return "number";
+
   if (type === "boolean") return "boolean";
+
   if (type === "null") return "null";
+
   return "unknown";
 }
 
-function renderZodPrimitive(type: unknown): string {
+function renderZodPrimitive(type: JsonValue | undefined): string {
   if (type === "string") return "z.string()";
+
   if (type === "number" || type === "integer") return "z.number()";
+
   if (type === "boolean") return "z.boolean()";
+
   if (type === "null") return "z.null()";
+
   return "z.unknown()";
 }
 
-function renderZodEnum(values: unknown[], enumValueLimit?: number): string {
+function renderZodEnum(values: JsonValue[], enumValueLimit?: number): string {
   if (values.length === 0) return "z.never()";
 
   const visibleValues =
     enumValueLimit === undefined ? values : values.slice(0, Math.max(0, enumValueLimit));
+
   const omittedCount = values.length - visibleValues.length;
   const suffix = omittedCount > 0 ? ` /* +${omittedCount} */` : "";
 
-  if (values.every((value) => typeof value === "string")) {
+  if (values.every((value) => z.string().safeParse(value).success)) {
     return `z.enum([${visibleValues.map((value) => JSON.stringify(value)).join(", ")}${suffix}])`;
   }
 
   const literals = visibleValues.map((value) => `z.literal(${JSON.stringify(value)})`);
+
   if (literals.length === 1 && omittedCount === 0) return literals[0] ?? "z.never()";
+
   return `z.union([${literals.join(", ")}${suffix}])`;
 }
 
-function renderZodNode(node: unknown, depth: number, enumValueLimit?: number): string {
+function schemaProperties(schema: JsonObject): JsonObject {
+  return isJsonObject(schema.properties) ? schema.properties : {};
+}
+
+function requiredKeys(schema: JsonObject): Set<string> {
+  const required = schema.required;
+
+  return new Set(
+    Array.isArray(required) ? required.flatMap((key) => z.string().safeParse(key).data ?? []) : [],
+  );
+}
+
+function renderZodNode(
+  node: JsonValue | undefined,
+  depth: number,
+  enumValueLimit?: number,
+): string {
   if (node === true) return "z.unknown()";
-  if (!node || typeof node !== "object" || Array.isArray(node)) return "z.unknown()";
-  const schema = node as SchemaNode;
+
+  if (!isJsonObject(node)) return "z.unknown()";
+  const schema = node;
 
   if (Array.isArray(schema.enum)) return renderZodEnum(schema.enum, enumValueLimit);
+
   if (schema.const !== undefined) return `z.literal(${JSON.stringify(schema.const)})`;
 
-  const variants = (schema.anyOf ?? schema.oneOf) as unknown;
+  const variants = schema.anyOf ?? schema.oneOf;
+
   if (Array.isArray(variants) && variants.length > 0) {
     const rendered = [
       ...new Set(variants.map((variant) => renderZodNode(variant, depth, enumValueLimit))),
     ];
+
     return rendered.length === 1
       ? (rendered[0] ?? "z.unknown()")
       : `z.union([${rendered.join(", ")}])`;
   }
 
   const type = schema.type;
+
   if (Array.isArray(type)) {
     const rendered = [...new Set(type.map(renderZodPrimitive))];
+
     return rendered.length === 1
       ? (rendered[0] ?? "z.unknown()")
       : `z.union([${rendered.join(", ")}])`;
   }
 
   if (type === "object" || (type === undefined && schema.properties)) {
-    const properties = (schema.properties ?? {}) as Record<string, unknown>;
-    const required = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
+    const properties = schemaProperties(schema);
+    const required = requiredKeys(schema);
     const keys = Object.keys(properties);
+
     if (keys.length === 0) return "z.object({})";
+
     const orderedKeys = [
       ...keys.filter((key) => required.has(key)),
       ...keys.filter((key) => !required.has(key)),
     ];
 
     const inner = "  ".repeat(depth + 1);
+
     const lines = orderedKeys.map((key) => {
       const propertySchema = properties[key];
       const rendered = renderZodNode(propertySchema, depth + 1, enumValueLimit);
       const optional = required.has(key) ? rendered : `${rendered}.optional()`;
+
       const defaultValue =
-        propertySchema &&
-        typeof propertySchema === "object" &&
-        !Array.isArray(propertySchema) &&
-        Object.hasOwn(propertySchema, "default")
-          ? JSON.stringify((propertySchema as SchemaNode).default)
+        isJsonObject(propertySchema) && Object.hasOwn(propertySchema, "default")
+          ? JSON.stringify(propertySchema.default)
           : undefined;
+
       const defaultComment = defaultValue === undefined ? "" : ` // default=${defaultValue}`;
+
       return `${inner}${renderKey(key)}: ${optional},${defaultComment}`;
     });
+
     return `z.object({\n${lines.join("\n")}\n${"  ".repeat(depth)}})`;
   }
 
@@ -111,43 +154,52 @@ function renderZodNode(node: unknown, depth: number, enumValueLimit?: number): s
   return renderZodPrimitive(type);
 }
 
-function renderNode(node: unknown, depth: number): string {
+function renderNode(node: JsonValue | undefined, depth: number): string {
   if (node === true) return "unknown";
-  if (!node || typeof node !== "object" || Array.isArray(node)) return "unknown";
-  const schema = node as SchemaNode;
+
+  if (!isJsonObject(node)) return "unknown";
+  const schema = node;
 
   if (Array.isArray(schema.enum)) {
     return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
   }
+
   if (schema.const !== undefined) return JSON.stringify(schema.const);
 
-  const variants = (schema.anyOf ?? schema.oneOf) as unknown;
+  const variants = schema.anyOf ?? schema.oneOf;
+
   if (Array.isArray(variants) && variants.length > 0) {
     return [...new Set(variants.map((variant) => renderNode(variant, depth)))].join(" | ");
   }
 
   const type = schema.type;
+
   if (Array.isArray(type)) {
     return [...new Set(type.map(renderPrimitive))].join(" | ");
   }
 
   if (type === "object" || (type === undefined && schema.properties)) {
-    const properties = (schema.properties ?? {}) as Record<string, unknown>;
-    const required = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
+    const properties = schemaProperties(schema);
+    const required = requiredKeys(schema);
     const keys = Object.keys(properties);
+
     if (keys.length === 0) return "Record<string, unknown>";
     const inner = "  ".repeat(depth + 1);
+
     const lines = keys.map(
       (key) =>
         `${inner}${renderKey(key)}${required.has(key) ? "" : "?"}: ${renderNode(properties[key], depth + 1)}`,
     );
+
     return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
   }
 
   if (type === "array") {
     const item = renderNode(schema.items, depth);
+
     // 유니온 요소는 괄호가 없으면 `A | B[]` 로 잘못 읽힌다.
     if (item.includes(" | ")) return `(${item})[]`;
+
     return `${item}[]`;
   }
 
@@ -155,19 +207,22 @@ function renderNode(node: unknown, depth: number): string {
 }
 
 /** 이미 파싱된 스키마 값용 — 호출부가 같은 JSON 을 두 번 파싱하지 않게 한다. */
-export function renderParsedJsonSchemaTypeText(schema: unknown, name = "Response"): string {
+export function renderParsedJsonSchemaTypeText(schema: JsonValue, name = "Response"): string {
   return `type ${name} = ${renderNode(schema, 0)}`;
 }
 
-/** Tool input 계약용 표시 전용 Zod shape. 검증 제약은 의도적으로 생략한다. */
-export function renderJsonSchemaZodShapeText(schema: unknown, enumValueLimit?: number): string {
+/** Tool input 계약용 표시 전용 Zod 코드. 검증 제약은 의도적으로 생략한다. */
+export function renderJsonSchemaZodText(schema: JsonValue, enumValueLimit?: number): string {
   return renderZodNode(schema, 0, enumValueLimit);
 }
 
 /** 실패(파싱 불가 등) 시 null — 호출부가 표시 자체를 생략한다. */
 export function renderJsonSchemaTypeText(schemaJson: string, name = "Response"): string | null {
   try {
-    return renderParsedJsonSchemaTypeText(JSON.parse(schemaJson) as unknown, name);
+    // JSON.parse without a reviver yields only JSON values.
+    const schema: JsonValue = JSON.parse(schemaJson);
+
+    return renderParsedJsonSchemaTypeText(schema, name);
   } catch {
     return null;
   }