@cartanova/qgrid-cli 2.5.3 → 2.5.5

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

@@ -1,6 +1,16 @@
+import { Buffer } from "node:buffer";
+
 import { getLogger } from "@logtape/logtape";
+import { z } from "zod";
 
-import { type JsonValue } from "../../codex-protocol/serde_json/JsonValue";
+// 응답(모델 출력) envelope 의 자원 한도. caller 스키마 전처리 한도(CALLER_SCHEMA_LIMITS)와 값이
+// 같아 보여도 서로 다른 자원을 지키는 독립 상수다 — 스키마 깊이는 인스턴스 깊이를 bound 하지
+// 않으므로(재귀 $ref 허용) 캘러 한도를 조정해도 응답 수용 기준이 따라 움직여선 안 된다.
+const STRUCTURED_ENVELOPE_LIMITS = {
+  maxUtf8Bytes: 512 * 1024,
+  maxNodes: 20_000,
+  maxDepth: 132,
+} as const;
 import {
   type QgridContent,
   type QgridThreadCoord,
@@ -10,136 +20,175 @@ import {
 
 const logger = getLogger(["qgrid", "tool-emulation"]);
 
-type ToolCallResponse = {
-  action: "answer" | "tool_call";
+type EmulationResult = Omit<QueryOutput, "content" | "finishReason" | "runContext">;
+type ToolCall = { toolName: string; args: string };
+type LegacyToolCallResponse = {
+  action?: "answer" | "tool_call";
   answer?: string | null;
-  toolCalls?: Array<{ toolName: string; args: string }> | null;
+  toolCalls?: ToolCall[] | null;
 };
 
+const StructuredToolCallResponse = z.discriminatedUnion("action", [
+  z.strictObject({
+    action: z.literal("answer"),
+    answer: z.json().refine((answer) => answer !== null, {
+      message: "answer must be non-null",
+    }),
+    toolCalls: z.union([z.null(), z.tuple([])]),
+  }),
+  z.strictObject({
+    action: z.literal("tool_call"),
+    answer: z.null(),
+    toolCalls: z
+      .array(
+        z.strictObject({
+          toolName: z.string(),
+          args: z.string(),
+        }),
+      )
+      .min(1),
+  }),
+]);
+type StructuredResponse = z.infer<typeof StructuredToolCallResponse>;
+
+export class ToolCallEmulationError extends Error {
+  constructor(message: string) {
+    super(`tool-call emulation: ${message}`);
+    this.name = "ToolCallEmulationError";
+  }
+}
+
 // dispatcher 가 넘기는 이미지 결과. qgrid 는 base64 payload 만 전달하고 포맷은 보장하지 않는다.
-export interface EmulationImage {
+interface EmulationImage {
   data: string;
   revisedPrompt?: string | null;
 }
 
-// 조립된 content 뒤에 이미지 파트를 append 한다. 모든 반환 분기가 공유.
-function appendImages(content: QgridContent[], images?: EmulationImage[]): QgridContent[] {
-  if (!images?.length) return content;
-  return [
-    ...content,
-    ...images.map(
-      (img): QgridContent => ({
-        type: "image",
-        data: img.data,
-        revisedPrompt: img.revisedPrompt ?? null,
-      }),
-    ),
-  ];
-}
-
-export function buildToolCallSchema(tools: QgridTool[]): JsonValue {
-  const toolDescriptions = tools
-    .map((tool) => {
-      const schema = JSON.stringify(tool.inputSchema);
-      return `- ${tool.name}: ${tool.description ?? ""}\n  inputSchema: ${schema}`;
-    })
-    .join("\n");
-
-  return {
-    type: "object",
-    description:
-      "Use this schema only through StructuredOutput. Do not invoke listed client tools as native Claude Code tools. To request client-side tool execution, set action to tool_call and include toolCalls. Use action answer only when no further client tool result is needed.",
-    properties: {
-      action: {
-        type: "string",
-        enum: ["answer", "tool_call"],
-        description:
-          "Use tool_call to request client-side tool execution through this structured output. Use answer only for a final answer.",
-      },
-      answer: { anyOf: [{ type: "string" }, { type: "null" }] },
-      toolCalls: {
-        description:
-          "Client-side tool calls requested through structured output. Do not call these tools as native Claude Code tools.",
-        anyOf: [
-          {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                toolName: {
-                  type: "string",
-                  enum: tools.map((tool) => tool.name),
-                  description: `Client-side tool name to request through structured output. Do not call this as a native Claude Code tool.\n${toolDescriptions}`,
-                },
-                args: {
-                  type: "string",
-                  description: "Tool arguments as a JSON string for the client-side tool.",
-                },
-              },
-              required: ["toolName", "args"],
-              additionalProperties: false,
-            },
-          },
-          { type: "null" },
-        ],
-      },
-    },
-    required: ["action", "answer", "toolCalls"],
-    additionalProperties: false,
-  };
+interface ToolCallEmulationOptions {
+  threadCoord?: QgridThreadCoord;
+  images?: EmulationImage[];
+  answerMode?: "legacy" | "structured";
 }
 
 export function applyToolCallEmulation(
-  result: Omit<QueryOutput, "content" | "finishReason" | "runContext">,
+  result: EmulationResult,
   tools?: QgridTool[],
-  threadCoord?: QgridThreadCoord,
-  images?: EmulationImage[],
+  options: ToolCallEmulationOptions = {},
 ): QueryOutput {
-  // thread 재사용 좌표를 runContext 로 실어 올린다 (auto 모드는 requestLogId 없이 threadCoord 만).
+  const { threadCoord, images, answerMode = "legacy" } = options;
   const runContext = threadCoord ? { threadCoord } : undefined;
-  // 이미지는 finishReason 과 직교하는 content 파트. 조립된 content 뒤에 append 한다.
 
   if (!tools?.length) {
-    const content: QgridContent[] = [{ type: "text", text: result.text }];
-    return { ...result, content: appendImages(content, images), finishReason: "stop", runContext };
+    return answerOutput(result, result.text, images, runContext);
   }
 
-  let parsed: ToolCallResponse;
+  if (answerMode === "legacy") {
+    return applyLegacyResponse(result, tools, images, runContext);
+  }
+
+  const parsed = parseStructuredResponse(result.text, tools);
+  if (parsed.action === "tool_call") {
+    return toolCallOutput(result, parsed.toolCalls, images, runContext);
+  }
+
+  return answerOutput(result, JSON.stringify(parsed.answer), images, runContext);
+}
+
+/**
+ * Tools-only requests keep the permissive 2.5.3 contract. Structured-output requests use the
+ * strict decoder below because their outer action envelope is an internal server contract.
+ */
+function applyLegacyResponse(
+  result: EmulationResult,
+  tools: QgridTool[],
+  images: EmulationImage[] | undefined,
+  runContext: QueryOutput["runContext"],
+): QueryOutput {
+  let parsed: LegacyToolCallResponse;
   try {
-    parsed = JSON.parse(result.text) as ToolCallResponse;
-  } catch (e) {
-    logger.warn(`tool-call emulation parse failed, falling back to text: ${(e as Error).message}`);
-    return {
-      ...result,
-      content: appendImages([{ type: "text", text: result.text }], images),
-      finishReason: "stop",
-      runContext,
-    };
+    parsed = JSON.parse(result.text) as LegacyToolCallResponse;
+  } catch (error) {
+    logger.warn(
+      `tool-call emulation parse failed, falling back to text: ${(error as Error).message}`,
+    );
+    return answerOutput(result, result.text, images, runContext);
   }
 
   if (parsed.action === "tool_call") {
     const toolCalls = parsed.toolCalls ?? [];
-    const content: QgridContent[] = toolCalls.map((toolCall) => {
-      if (!tools.some((tool) => tool.name === toolCall.toolName)) {
-        throw new Error(`unknown emulated tool: ${toolCall.toolName}`);
-      }
+    const unknownTool = findUnknownTool(toolCalls, tools);
+    if (unknownTool !== undefined) throw new Error(`unknown emulated tool: ${unknownTool}`);
+    return toolCallOutput(result, toolCalls, images, runContext);
+  }
+
+  return answerOutput(result, parsed.answer ?? result.text, images, runContext);
+}
 
-      return {
+function parseStructuredResponse(text: string, tools: QgridTool[]) {
+  if (Buffer.byteLength(text, "utf8") > STRUCTURED_ENVELOPE_LIMITS.maxUtf8Bytes) {
+    throw new ToolCallEmulationError(
+      `structured-output envelope exceeds UTF-8 byte limit of ${STRUCTURED_ENVELOPE_LIMITS.maxUtf8Bytes}`,
+    );
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new ToolCallEmulationError(
+      `invalid structured-output envelope: ${(error as Error).message}`,
+    );
+  }
+
+  assertStructuredEnvelopeComplexity(value);
+  const validation = StructuredToolCallResponse.safeParse(value);
+  if (!validation.success) {
+    const issue = validation.error.issues[0];
+    const path = issue && issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+    const detail = issue?.message ?? "unknown validation issue";
+    throw new ToolCallEmulationError(`invalid structured-output envelope${path}: ${detail}`);
+  }
+
+  // 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.
+  const response = value as StructuredResponse;
+  if (response.action === "tool_call") {
+    const unknownTool = findUnknownTool(response.toolCalls, tools);
+    if (unknownTool !== undefined) {
+      throw new ToolCallEmulationError(`unknown emulated tool: ${unknownTool}`);
+    }
+  }
+  return response;
+}
+
+function toolCallOutput(
+  result: EmulationResult,
+  toolCalls: ToolCall[],
+  images: EmulationImage[] | undefined,
+  runContext: QueryOutput["runContext"],
+): QueryOutput {
+  return {
+    ...result,
+    content: appendImages(
+      toolCalls.map((toolCall) => ({
         type: "tool-call",
         toolCallId: `call_${Math.random().toString(36).slice(2, 10)}`,
         toolName: toolCall.toolName,
         input: toolCall.args,
-      };
-    });
-    return {
-      ...result,
-      content: appendImages(content, images),
-      finishReason: "tool-calls",
-      runContext,
-    };
-  }
+      })),
+      images,
+    ),
+    finishReason: "tool-calls",
+    runContext,
+  };
+}
 
-  const text = parsed.answer ?? result.text;
+function answerOutput(
+  result: EmulationResult,
+  text: string,
+  images: EmulationImage[] | undefined,
+  runContext: QueryOutput["runContext"],
+): QueryOutput {
   return {
     ...result,
     text,
@@ -148,3 +197,51 @@ export function applyToolCallEmulation(
     runContext,
   };
 }
+
+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 => ({
+        type: "image",
+        data: image.data,
+        revisedPrompt: image.revisedPrompt ?? null,
+      }),
+    ),
+  ];
+}
+
+function assertStructuredEnvelopeComplexity(root: unknown): void {
+  const maxDepth = STRUCTURED_ENVELOPE_LIMITS.maxDepth;
+  const stack = [{ 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)) {
+      throw new ToolCallEmulationError("answer must be valid JSON");
+    }
+    if (current.value === null || typeof current.value !== "object") continue;
+
+    for (const value of Object.values(current.value)) {
+      stack.push({ value, depth: current.depth + 1 });
+    }
+  }
+}

package/bundle/src/server-error-handler.ts

@@ -0,0 +1,22 @@
+import { getLogger } from "@logtape/logtape";
+import { type FastifyReply } from "fastify";
+import { isSoException } from "sonamu";
+
+// statusCode 를 신뢰하는 범위를 Sonamu 예외 계약(isSoException)으로 한정한다. qgrid 는 프록시라
+// upstream HTTP 오류(fetch/undici 류)도 statusCode 를 달고 나오는데, 그걸 duck-typing 으로
+// 그대로 에코하면 upstream 의 401/429 가 호출자 자신의 오류로 둔갑한다. Sonamu 예외가 아니면 500.
+export function handleServerError(error: Error, reply: FastifyReply): void {
+  getLogger(["qgrid"]).error(`${error}`);
+  const statusCode =
+    isSoException(error) &&
+    Number.isInteger(error.statusCode) &&
+    error.statusCode >= 400 &&
+    error.statusCode <= 599
+      ? error.statusCode
+      : 500;
+
+  reply.status(statusCode).send({
+    name: error.name,
+    message: error.message,
+  });
+}

package/bundle/src/sonamu.config.test.ts

@@ -0,0 +1,37 @@
+import { BadRequestException } from "sonamu";
+import { describe, expect, it, vi } from "vitest";
+
+import { handleServerError } from "./server-error-handler";
+
+function createReply() {
+  const send = vi.fn();
+  const status = vi.fn(() => ({ send }));
+  return { reply: { status } as never, send, status };
+}
+
+describe("handleServerError", () => {
+  it("preserves explicit client error status codes", () => {
+    const { reply, send, status } = createReply();
+    const error = new BadRequestException("invalid schema" as never);
+
+    handleServerError(error, reply);
+
+    expect(status).toHaveBeenCalledWith(400);
+    expect(send).toHaveBeenCalledWith({
+      name: error.name,
+      message: "invalid schema",
+    });
+  });
+
+  it.each([
+    ["ordinary errors", new Error("provider failed")],
+    ["invalid success-like status codes", Object.assign(new Error("wrong status"), { statusCode: 200 })],
+    ["out-of-range status codes", Object.assign(new Error("wrong status"), { statusCode: 700 })],
+  ])("keeps %s as internal server errors", (_label, error) => {
+    const { reply, status } = createReply();
+
+    handleServerError(error, reply);
+
+    expect(status).toHaveBeenCalledWith(500);
+  });
+});

package/bundle/src/sonamu.config.ts

@@ -11,6 +11,7 @@ import { QgridDispatcher } from "./application/qgrid/qgrid.dispatcher";
 import { QgridFrame } from "./application/qgrid/qgrid.frame";
 import { TokenSubscriber } from "./application/qgrid/token-subscriber";
 import { ensureTokensTrigger } from "./application/qgrid/token-trigger-setup";
+import { handleServerError } from "./server-error-handler";
 import { AnthropicDispatcher } from "./utils/providers/anthropic/anthropic-dispatcher";
 import { OpenAIDispatcher } from "./utils/providers/openai/openai-dispatcher";
 
@@ -219,11 +220,7 @@ export default defineConfig({
         log.info("graceful shutdown");
       },
       onError: (error, _request, reply) => {
-        getLogger(["qgrid"]).error(`${error}`);
-        reply.status(500).send({
-          name: error.name,
-          message: error.message,
-        });
+        handleServerError(error, reply);
       },
     },
   },

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
+import { ToolCallEmulationError } from "../../../application/qgrid/tool-emulation";
 import { type AnthropicCredentials } from "../../../application/token/token.types";
 import { type GenerateRequest } from "../common/provider-dispatcher";
 import { ANTHROPIC_DEFAULT_MODEL } from "./anthropic-constants";
@@ -175,6 +176,23 @@ describe("AnthropicDispatcher", () => {
     expect(call.jsonSchema).toBe(JSON.stringify({ type: "object", properties: {} }));
   });
 
+  it("argv 안전 한도를 넘는 structured schema를 session 실행 전에 거부한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+
+    await expect(
+      d.generate(
+        baseReq({
+          outputSchema: {
+            type: "object",
+            description: "x".repeat(64 * 1024),
+          },
+        }),
+      ),
+    ).rejects.toThrow("Anthropic dispatch schema exceeds argv UTF-8 byte limit");
+    expect(runClaudeSessionMock).not.toHaveBeenCalled();
+  });
+
   it("요청 timeoutMs를 Claude session에 전달하고 미지정 시 240초 기본값을 쓴다", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds(), null, 1);
@@ -470,6 +488,32 @@ describe("AnthropicDispatcher", () => {
     expect(firstRunRequest().includePartialMessages).toBe(true);
   });
 
+  it("generateStream: completion callback throw를 onError로 전달하고 정상 종료한다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+    runClaudeSessionMock.mockResolvedValueOnce(sessionResult({ text: "malformed envelope" }));
+    const completionError = new ToolCallEmulationError(
+      "response envelope is missing required keys: toolCalls",
+    );
+    const onComplete = vi.fn(() => {
+      throw completionError;
+    });
+    const onError = vi.fn();
+
+    await expect(
+      d.generateStream(baseReq(), {
+        onDelta: vi.fn(),
+        onComplete,
+        onError,
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(onComplete).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith(completionError);
+    expect(firstRunRequest().includePartialMessages).toBe(true);
+  });
+
   it("generateStream: Claude server error 는 onError 로 전달하고 complete 하지 않는다", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds(), null, 1);

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -23,6 +23,7 @@ import {
   type GenerateStreamCallbacks,
   type ProviderDispatcher,
 } from "../common/provider-dispatcher";
+import { serializeAndValidateDispatchSchema } from "../common/schema-validation";
 import { SmoothWeightedRoundRobin } from "../common/smooth-weighted-round-robin";
 import { assertSupportedOneMillionSuffix, canonicalAnthropicModel } from "./anthropic-constants";
 import { readAnthropicQuotaUsage, type AnthropicQuotaUsageResult } from "./anthropic-quota";
@@ -287,8 +288,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     // 의 "sonnet" 별칭 우회 차단. 정규화 규칙은 fallback 경로와 공유(canonicalAnthropicModel).
     assertSupportedOneMillionSuffix(req.model);
     const model = canonicalAnthropicModel(req.model);
-    const jsonSchema =
-      req.outputSchema !== undefined ? JSON.stringify(req.outputSchema) : undefined;
+    const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
 
     const token = await this.selectToken();
     if (!token) throw new Error("No anthropic tokens available");

package/bundle/src/utils/providers/anthropic/claude-session.test.ts

@@ -234,6 +234,16 @@ describe("buildClaudeArgs (멀티턴/격리/structured)", () => {
     expect(args).not.toContain("--max-turns");
   });
 
+  it("argv 안전 한도를 넘는 structured schema를 spawn 전에 거부한다", () => {
+    expect(() =>
+      buildClaudeArgs({
+        model: "m",
+        sessionId: "u",
+        jsonSchema: "x".repeat(SYSTEM_PROMPT_ARGV_MAX_BYTES + 1),
+      }),
+    ).toThrow("Anthropic dispatch schema exceeds argv UTF-8 byte limit");
+  });
+
   it("1M suffix 는 CLI --model 인자에만 반영된다", () => {
     const args = buildClaudeArgs({
       model: "claude-sonnet-4-6",

package/bundle/src/utils/providers/anthropic/claude-session.ts

@@ -21,6 +21,10 @@ import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
 import { type TokenUsageBreakdown } from "../../../codex-protocol/v2/TokenUsageBreakdown";
 import { type UserInput } from "../../../codex-protocol/v2/UserInput";
+import {
+  ARGV_SAFE_MAX_UTF8_BYTES,
+  assertAnthropicSchemaArgvSize,
+} from "../common/schema-validation";
 import { createTtftTracker } from "../common/ttft";
 import {
   ANTHROPIC_CLAUDE_CWD,
@@ -191,7 +195,7 @@ export function shouldPinStructuredRetries(opts: {
 // 시스템 프롬프트가 이를 넘으면 execve 가 E2BIG 로 거부된다. deti 등 대형 프롬프트는 실측
 // 평균 343KB·최대 485KB(opus-4-8)라 일상적으로 초과한다. 한계의 절반(64KB)을 임계값으로 잡아
 // UTF-8 멀티바이트·예측 못 한 여유분까지 안전 마진을 둔다.
-export const SYSTEM_PROMPT_ARGV_MAX_BYTES = 64 * 1024;
+export const SYSTEM_PROMPT_ARGV_MAX_BYTES = ARGV_SAFE_MAX_UTF8_BYTES;
 
 export function buildClaudeArgs(opts: {
   model: string;
@@ -209,6 +213,7 @@ export function buildClaudeArgs(opts: {
   includePartialMessages?: boolean;
 }): Array<string> {
   const useStructured = Boolean(opts.jsonSchema && opts.jsonSchema.length > 0);
+  if (useStructured) assertAnthropicSchemaArgvSize(opts.jsonSchema!);
   // --tools "" 로 전체 차단, structured(jsonSchema 있음) 면 StructuredOutput 만 허용.
   const toolArgs = useStructured
     ? ["--tools", "", "--allowed-tools", "StructuredOutput"]

package/bundle/src/utils/providers/common/json-schema-keywords.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema 하위 스키마 위치 목록 — qgrid 의 스키마 순회 3곳이 공유하는 단일 정본.
+ *
+ *  - `tool-emulation-schema.rewriteSchemaNode`: 사용자 스키마의 local `$ref` 를 namespace 로 rebase
+ *  - `strictifier.assertNormalizationCompatibility`: provider 표현 가능성 검사
+ *  - `strictifier.strictifyNode`: strict 재작성
+ *
+ * 세 소비자가 각자 테이블을 들고 있으면 새 keyword 를 한쪽에만 추가하는 순간 조용히 어긋난다.
+ * 재작성 패스가 훑지 않는 위치의 `$ref` 는 rebase 되지 않은 채 남고, 검사 패스가 놓친 위치의
+ * tuple 은 정규화 없이 provider 로 샌다. 실제로 통합 전 `additionalItems` 가 그 상태였다.
+ * 위치 목록은 여기서만 관리한다.
+ *
+ * 왜 이런 순회가 필요한지는 스킬 문서 참고:
+ *   packages/cli/skills/qgrid/references/tool-calling-and-multiturn.md
+ *
+ * 소비자별로 다른 것은 위치 목록이 아니라 **각 위치를 어떻게 다루는가** 이므로(strictifier 의
+ * `normalizable` 플래그 등) 그 판단은 각 소비자가 이 목록 위에 얹는다.
+ */
+
+/** 이름 → 하위 스키마 맵. 예: `properties`, `$defs`. */
+export const SCHEMA_MAP_KEYWORDS = [
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+] as const;
+
+/** 하위 스키마 배열. 예: `anyOf`, `prefixItems`. */
+export const SCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
+
+/**
+ * 하위 스키마 하나를 직접 갖는 위치. `items` 와 `additionalItems` 는 Draft-7 tuple 형식에서
+ * 배열이 올 수 있으므로 소비자가 배열 분기를 따로 처리한다.
+ */
+export const SCHEMA_SINGLE_KEYWORDS = [
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+] as const;
+
+/**
+ * Draft-7 `dependencies` 는 값이 스키마이거나 property 이름 배열이라 위 분류에 들어가지 않는다.
+ * 배열 형태는 스키마가 아니므로 순회 대상이 아니다.
+ */
+export const SCHEMA_DEPENDENCIES_KEYWORD = "dependencies";
+
+/**
+ * qgrid 가 거부하는 참조/식별 keyword.
+ *
+ * 사용자 스키마는 envelope 의 `$defs` 아래로 옮겨지고 정의는 전역적으로 정규화되므로, base URI 를
+ * 새로 선언하거나(`$id`) 런타임 스코프로 대상이 정해지는 참조(`$dynamicRef` 등)는 옮긴 뒤의 의미를
+ * 보장할 수 없다. 조용히 잘못 rebase 하는 대신 명시적으로 거부한다.
+ */
+export const UNSUPPORTED_REFERENCE_KEYWORDS = [
+  "$id",
+  "id",
+  "$anchor",
+  "$dynamicAnchor",
+  "$recursiveAnchor",
+  "$dynamicRef",
+  "$recursiveRef",
+] as const;