@cartanova/qgrid-cli 2.10.10 → 2.11.0

package/bundle/src/utils/providers/common/strictifier.ts

@@ -8,14 +8,23 @@
  *  - recursive 처리 (nested objects, arrays, allOf/anyOf/oneOf)
  */
 
+import { z } from "zod";
+
 import {
   SCHEMA_ARRAY_KEYWORDS,
   SCHEMA_MAP_KEYWORDS,
   SCHEMA_SINGLE_KEYWORDS,
   UNSUPPORTED_REFERENCE_KEYWORDS,
 } from "./json-schema-keywords";
+import {
+  isJsonObject,
+  type JsonObject,
+  type JsonValue,
+  type ReadonlyJsonObject,
+} from "./provider-types";
 
-export type JsonSchema = Record<string, unknown>;
+/** An object-form JSON Schema node. Boolean schemas and malformed members stay plain JSON values. */
+export type JsonSchema = JsonObject;
 
 export interface StrictifierOptions {
   provider?: string;
@@ -31,14 +40,24 @@ export class StrictifierError extends Error {
   }
 }
 
-export function strictify(schema: JsonSchema, options: StrictifierOptions = {}): JsonSchema {
+export function strictify(input: ReadonlyJsonObject, options: StrictifierOptions = {}): JsonSchema {
+  // Work on the JSON the provider will receive: a fresh copy, with undefined members dropped as
+  // serialization drops them. JSON.parse without a reviver yields only JSON values.
+  const serialized: JsonValue = JSON.parse(JSON.stringify(input));
+
+  if (!isSchemaObject(serialized)) throw new StrictifierError("schema must be an object", "$");
+  const schema = serialized;
+
   if (options.provider === "openai" || options.provider === "anthropic") {
     assertNormalizationCompatibility(schema, options.provider);
   }
+
   const result = strictifyNode(schema, "$", options.provider);
+
   if (options.provider === "openai" || options.provider === "anthropic") {
     assertNormalizationCompatibility(result, options.provider);
   }
+
   return result;
 }
 
@@ -70,6 +89,7 @@ function positionEntries(keywords: readonly string[]): ReadonlyArray<readonly [s
 
 const SCHEMA_SCAN_MAP_KEYWORDS = positionEntries(SCHEMA_MAP_KEYWORDS);
 const SCHEMA_SCAN_ARRAY_KEYWORDS = positionEntries(SCHEMA_ARRAY_KEYWORDS);
+
 // items/additionalItems 는 tuple 분기에서 직접 다루므로 단일 위치 스캔에서 제외한다.
 const SCHEMA_SCAN_SINGLE_KEYWORDS = positionEntries(
   SCHEMA_SINGLE_KEYWORDS.filter((keyword) => keyword !== "items" && keyword !== "additionalItems"),
@@ -88,6 +108,7 @@ function assertNormalizationCompatibility(
   provider: "openai" | "anthropic",
 ): void {
   const references: Array<{ value: string; path: string }> = [];
+
   const stack: Array<{ node: JsonSchema; path: string; normalizable: boolean }> = [
     { node: schema, path: "$", normalizable: true },
   ];
@@ -103,19 +124,22 @@ function assertNormalizationCompatibility(
     collectSchemaReference(current, references);
 
     if (legacyTuple || prefixTuple) {
-      const tuple = (legacyTuple ? itemsValue : prefixItemsValue) as unknown[];
+      const tuple = legacyTuple ? itemsValue : prefixTuple ? prefixItemsValue : [];
+
       if (provider === "anthropic" && tuple.length > 0) {
         throw new StrictifierError(
           "positional tuple schemas are not supported on Anthropic because Claude Code cannot preserve item positions",
           current.path,
         );
       }
+
       if (!current.normalizable) {
         throw new StrictifierError(
           "positional tuple schemas are not supported in this schema position",
           current.path,
         );
       }
+
       if (ownValue(current.node, "type") !== "array") {
         throw new StrictifierError(
           'positional tuple schemas must declare type "array"; express nullable tuples with anyOf',
@@ -126,7 +150,9 @@ function assertNormalizationCompatibility(
 
     for (const [keyword, keywordNormalizable] of SCHEMA_SCAN_MAP_KEYWORDS) {
       const schemas = ownValue(current.node, keyword);
+
       if (!isSchemaObject(schemas)) continue;
+
       for (const [name, child] of Object.entries(schemas)) {
         if (!isSchemaObject(child)) continue;
         stack.push({
@@ -138,6 +164,7 @@ function assertNormalizationCompatibility(
     }
 
     const dependencies = ownValue(current.node, "dependencies");
+
     if (isSchemaObject(dependencies)) {
       for (const [name, child] of Object.entries(dependencies)) {
         if (!isSchemaObject(child)) continue;
@@ -151,9 +178,12 @@ function assertNormalizationCompatibility(
 
     for (const [keyword, keywordNormalizable] of SCHEMA_SCAN_ARRAY_KEYWORDS) {
       const schemas = ownValue(current.node, keyword);
+
       if (!Array.isArray(schemas)) continue;
+
       for (let index = 0; index < schemas.length; index += 1) {
         const child = schemas[index];
+
         if (!isSchemaObject(child)) continue;
         stack.push({
           node: child,
@@ -164,6 +194,7 @@ function assertNormalizationCompatibility(
     }
 
     const items = ownValue(current.node, "items");
+
     if (isSchemaObject(items)) {
       stack.push({
         node: items,
@@ -173,6 +204,7 @@ function assertNormalizationCompatibility(
     } else if (Array.isArray(items)) {
       for (let index = 0; index < items.length; index += 1) {
         const child = items[index];
+
         if (!isSchemaObject(child)) continue;
         stack.push({
           node: child,
@@ -183,6 +215,7 @@ function assertNormalizationCompatibility(
     }
 
     const additionalItems = ownValue(current.node, "additionalItems");
+
     if (isSchemaObject(additionalItems)) {
       stack.push({
         node: additionalItems,
@@ -193,6 +226,7 @@ function assertNormalizationCompatibility(
 
     for (const [keyword, keywordNormalizable] of SCHEMA_SCAN_SINGLE_KEYWORDS) {
       const child = ownValue(current.node, keyword);
+
       if (!isSchemaObject(child)) continue;
       stack.push({
         node: child,
@@ -220,9 +254,12 @@ function collectSchemaReference(
   if (!Object.hasOwn(current.node, "$ref")) return;
 
   const reference = current.node.$ref;
-  if (typeof reference !== "string") {
+  const referenceText = z.string().safeParse(reference);
+
+  if (!referenceText.success) {
     throw new StrictifierError("$ref must be a string", `${current.path}.$ref`);
   }
+
   if (!current.normalizable) {
     throw new StrictifierError(
       "schema references are not supported in this schema position",
@@ -230,7 +267,7 @@ function collectSchemaReference(
     );
   }
 
-  references.push({ value: reference, path: `${current.path}.$ref` });
+  references.push({ value: referenceText.data, path: `${current.path}.$ref` });
 }
 
 function assertReferenceTargets(
@@ -239,28 +276,33 @@ function assertReferenceTargets(
 ): void {
   for (const reference of references) {
     const tokens = parseLocalJsonPointer(reference.value, reference.path);
+
     if (!isDefinitionRootPointer(tokens)) {
       throw new StrictifierError(
         "$ref target must be the document root or a definition root",
         reference.path,
       );
     }
+
     resolveDefinitionRoot(root, tokens, reference.path);
   }
 }
 
 function isDefinitionRootPointer(tokens: string[]): boolean {
   if (tokens.length === 0) return true;
+
   if (tokens.length % 2 !== 0) return false;
 
   for (let index = 0; index < tokens.length; index += 2) {
     if (tokens[index] !== "$defs" && tokens[index] !== "definitions") return false;
   }
+
   return true;
 }
 
 function parseLocalJsonPointer(reference: string, path: string): string[] {
   if (reference === "#") return [];
+
   if (!reference.startsWith("#/")) {
     throw new StrictifierError(
       "only local root-relative JSON Pointer $ref values are supported",
@@ -269,11 +311,13 @@ function parseLocalJsonPointer(reference: string, path: string): string[] {
   }
 
   let fragment: string;
+
   try {
     fragment = decodeURIComponent(reference.slice(1));
   } catch {
     throw new StrictifierError("$ref contains invalid percent encoding", path);
   }
+
   if (!fragment.startsWith("/")) {
     throw new StrictifierError(
       "only local root-relative JSON Pointer $ref values are supported",
@@ -289,31 +333,39 @@ function parseLocalJsonPointer(reference: string, path: string): string[] {
 
 function resolveDefinitionRoot(root: JsonSchema, tokens: string[], path: string): void {
   let current = root;
+
   for (let index = 0; index < tokens.length; index += 2) {
     const keyword = tokens[index]!;
     const name = tokens[index + 1]!;
     const definitions = ownValue(current, keyword);
+
     if (!isSchemaObject(definitions) || !Object.hasOwn(definitions, name)) {
       throw new StrictifierError("$ref does not resolve inside the caller schema", path);
     }
+
     const target = definitions[name];
+
     if (!isSchemaObject(target)) {
       throw new StrictifierError("$ref target must be an object schema", path);
     }
+
     current = target;
   }
 }
 
 function decodeJsonPointerToken(rawToken: string, path: string): string {
   let token = "";
+
   for (let index = 0; index < rawToken.length; index += 1) {
     const character = rawToken[index]!;
+
     if (character !== "~") {
       token += character;
       continue;
     }
 
     const escaped = rawToken[index + 1];
+
     if (escaped === "0") {
       token += "~";
     } else if (escaped === "1") {
@@ -321,17 +373,17 @@ function decodeJsonPointerToken(rawToken: string, path: string): string {
     } else {
       throw new StrictifierError("$ref contains an invalid JSON Pointer escape", path);
     }
+
     index += 1;
   }
+
   return token;
 }
 
 function strictifyNode(node: JsonSchema, path: string, provider?: string): JsonSchema {
-  if (typeof node !== "object" || node === null) return node;
-
   const dialectNeutralNode = provider === "openai" ? omitKeys(node, ["$schema"]) : node;
   let result = strictifySchemaMaps(dialectNeutralNode, path, provider);
-  const type = ownValue(result, "type") as string | undefined;
+  const type = ownValue(result, "type");
 
   if (type === "object" || Object.hasOwn(result, "properties")) {
     result = strictifyObject(result, path, provider);
@@ -344,6 +396,11 @@ function strictifyNode(node: JsonSchema, path: string, provider?: string): JsonS
   return strictifySchemaArrays(result, path, provider);
 }
 
+/** Boolean and other non-object subschemas pass through unchanged. */
+function strictifySubschema(schema: JsonValue, path: string, provider?: string): JsonValue {
+  return isSchemaObject(schema) ? strictifyNode(schema, path, provider) : schema;
+}
+
 // 재작성 패스는 정의 맵만 재귀한다. properties 는 strictifyObject 가 별도로 처리하므로
 // 공유 위치 목록(SCHEMA_MAP_KEYWORDS)과 의도적으로 범위가 다르다.
 const DEFINITION_MAP_KEYWORDS = ["$defs", "definitions"] as const;
@@ -353,14 +410,15 @@ function strictifySchemaMaps(node: JsonSchema, path: string, provider?: string):
 
   for (const keyword of DEFINITION_MAP_KEYWORDS) {
     const schemas = ownValue(node, keyword);
+
     if (!isSchemaObject(schemas)) continue;
 
     result[keyword] = Object.fromEntries(
       Object.entries(schemas).map(([name, schema]) => [
         name,
-        isSchemaObject(schema)
-          ? strictifyNode(schema, `${path}.${keyword}.${name}`, provider)
-          : schema,
+        schema === undefined
+          ? schema
+          : strictifySubschema(schema, `${path}.${keyword}.${name}`, provider),
       ]),
     );
   }
@@ -376,9 +434,15 @@ function strictifySchemaArrays(node: JsonSchema, path: string, provider?: string
 
   for (const keyword of COMBINATOR_KEYWORDS) {
     const schemas = ownValue(node, keyword);
+
     if (!schemas) continue;
-    result[keyword] = (schemas as JsonSchema[]).map((schema, index) =>
-      strictifyNode(schema, `${path}.${keyword}[${index}]`, provider),
+
+    if (!Array.isArray(schemas)) {
+      throw new StrictifierError(`${keyword} must be an array of schemas`, `${path}.${keyword}`);
+    }
+
+    result[keyword] = schemas.map((schema, index) =>
+      strictifySubschema(schema, `${path}.${keyword}[${index}]`, provider),
     );
   }
 
@@ -386,35 +450,48 @@ function strictifySchemaArrays(node: JsonSchema, path: string, provider?: string
 }
 
 function strictifyObject(node: JsonSchema, path: string, provider?: string): JsonSchema {
-  const properties = ownValue(node, "properties") as Record<string, JsonSchema> | undefined;
+  const properties = ownValue(node, "properties");
+
   if (!properties) {
     return { ...node, additionalProperties: false };
   }
 
-  const existingRequired = new Set((ownValue(node, "required") as string[] | undefined) ?? []);
+  if (!isSchemaObject(properties)) {
+    throw new StrictifierError("properties must be an object", `${path}.properties`);
+  }
+
+  const required = ownValue(node, "required");
+
+  const existingRequired = new Set(
+    Array.isArray(required) ? required.flatMap((key) => z.string().safeParse(key).data ?? []) : [],
+  );
+
   const allKeys = Object.keys(properties);
 
+  // Object.fromEntries defines own data properties, so names such as "__proto__" stay ordinary keys.
   const strictProps = Object.fromEntries(
-    allKeys.map((key) => {
-      const prop = properties[key]!;
-      const strictProp = strictifyNode(prop, `${path}.${key}`, provider);
+    allKeys.flatMap((key) => {
+      const prop = properties[key];
 
-      return [key, existingRequired.has(key) ? strictProp : makeNullable(strictProp)];
+      if (prop === undefined) return [];
+      const strictProp = strictifySubschema(prop, `${path}.${key}`, provider);
+
+      return [[key, existingRequired.has(key) ? strictProp : makeNullable(strictProp)]];
     }),
-  ) as Record<string, JsonSchema>;
+  );
 
-  const result: JsonSchema = {
+  return {
     ...node,
     type: "object",
     properties: strictProps,
     required: allKeys,
     additionalProperties: false,
   };
-
-  return result;
 }
 
-const UNREACHABLE_TUPLE_TAIL_SCHEMA: JsonSchema = { type: "string" };
+function unreachableTupleTailSchema(): JsonSchema {
+  return { type: "string" };
+}
 
 function strictifyArray(node: JsonSchema, path: string, provider?: string): JsonSchema {
   if (
@@ -425,20 +502,21 @@ function strictifyArray(node: JsonSchema, path: string, provider?: string): Json
   }
 
   const result = { ...node };
-  const items = ownValue(node, "items") as JsonSchema | JsonSchema[] | undefined;
+  const items = ownValue(node, "items");
 
   if (Array.isArray(items)) {
     result.items = items.map((schema, index) =>
-      strictifyNode(schema, `${path}.items[${index}]`, provider),
+      strictifySubschema(schema, `${path}.items[${index}]`, provider),
     );
   } else if (items !== undefined) {
-    result.items = strictifyNode(items, `${path}.items`, provider);
+    result.items = strictifySubschema(items, `${path}.items`, provider);
   }
 
-  const prefixItems = ownValue(node, "prefixItems") as JsonSchema[] | undefined;
+  const prefixItems = ownValue(node, "prefixItems");
+
   if (Array.isArray(prefixItems)) {
     result.prefixItems = prefixItems.map((schema, index) =>
-      strictifyNode(schema, `${path}.prefixItems[${index}]`, provider),
+      strictifySubschema(schema, `${path}.prefixItems[${index}]`, provider),
     );
   }
 
@@ -454,15 +532,18 @@ function normalizeTuple(
   const prefixItems = ownValue(node, "prefixItems");
   const legacyTuple = Array.isArray(items);
   const prefixTuple = Array.isArray(prefixItems);
+
   if (legacyTuple && prefixTuple) {
     throw new StrictifierError("items and prefixItems tuple forms cannot be combined", path);
   }
+
   if (prefixTuple && Object.hasOwn(node, "additionalItems")) {
     throw new StrictifierError("additionalItems cannot be combined with prefixItems", path);
   }
 
-  const rawTuple = (legacyTuple ? items : prefixItems) as unknown[];
+  const rawTuple = legacyTuple ? items : prefixTuple ? prefixItems : [];
   const tuplePath = legacyTuple ? `${path}.items` : `${path}.prefixItems`;
+
   const tuple = rawTuple.map((schema, index) => {
     if (!isSchemaObject(schema)) {
       throw new StrictifierError(
@@ -470,21 +551,26 @@ function normalizeTuple(
         `${tuplePath}[${index}]`,
       );
     }
+
     const memberPath = `${tuplePath}[${index}]`;
     const member = strictifyNode(schema, memberPath, provider);
+
     if (!hasProviderSchemaEntryPoint(member)) {
       throw new StrictifierError(
         "tuple member must define a provider-representable schema",
         memberPath,
       );
     }
+
     return member;
   });
 
   const rawTail = legacyTuple ? ownValue(node, "additionalItems") : items;
+
   if (rawTail === true) {
     throw new StrictifierError("an unrestricted tuple rest is not supported", path);
   }
+
   if (rawTail !== undefined && rawTail !== false && !isSchemaObject(rawTail)) {
     throw new StrictifierError("tuple rest must be an object schema or false", path);
   }
@@ -492,22 +578,37 @@ function normalizeTuple(
   const tail = isSchemaObject(rawTail)
     ? strictifyNode(rawTail, legacyTuple ? `${path}.additionalItems` : `${path}.items`, provider)
     : undefined;
+
   if (tail !== undefined && !hasProviderSchemaEntryPoint(tail)) {
     throw new StrictifierError("an unrestricted tuple rest is not supported", path);
   }
+
   const tailMode = tail !== undefined ? "typed" : rawTail === false ? "closed" : "implicit";
   const bounds = normalizeTupleBounds(node, tuple.length, tailMode, path);
-  const base = omitKeys(node, ["items", "prefixItems", "additionalItems", "minItems", "maxItems"]);
+
+  const result = omitKeys(node, [
+    "items",
+    "prefixItems",
+    "additionalItems",
+    "minItems",
+    "maxItems",
+  ]);
 
   // Anthropic 은 assertNormalizationCompatibility 가 비어 있지 않은 tuple 을 이미 거부했으므로
-  // 여기 도달하는 tuple 은 빈 tuple 뿐이고, 그 경우 prefixItems spread 는 자연히 생략된다 —
+  // 여기 도달하는 tuple 은 빈 tuple 뿐이고, 그 경우 prefixItems 는 생략된다 —
   // provider 분기 없이 한 형태로 두 provider 모두를 표현한다.
-  return {
-    ...base,
-    ...(tuple.length > 0 ? { prefixItems: tuple } : {}),
-    items: tail ?? UNREACHABLE_TUPLE_TAIL_SCHEMA,
-    ...bounds,
-  };
+  if (tuple.length > 0) result.prefixItems = tuple;
+  result.items = tail ?? unreachableTupleTailSchema();
+  result.minItems = bounds.minItems;
+
+  if (bounds.maxItems !== undefined) result.maxItems = bounds.maxItems;
+
+  return result;
+}
+
+interface TupleBounds {
+  minItems: number;
+  maxItems?: number;
 }
 
 function normalizeTupleBounds(
@@ -515,9 +616,10 @@ function normalizeTupleBounds(
   tupleLength: number,
   tailMode: "typed" | "closed" | "implicit",
   path: string,
-): { minItems: number; maxItems?: number } {
+): TupleBounds {
   const callerMinItems = integerBound(ownValue(node, "minItems"), "minItems", path);
   const callerMaxItems = integerBound(ownValue(node, "maxItems"), "maxItems", path);
+
   if (tailMode === "implicit" && callerMaxItems !== undefined && callerMaxItems > tupleLength) {
     throw new StrictifierError(
       "implicit tuple rest cannot be represented when maxItems exceeds the tuple length",
@@ -526,6 +628,7 @@ function normalizeTupleBounds(
   }
 
   const minItems = callerMinItems ?? (callerMaxItems === undefined ? tupleLength : 0);
+
   const maxItems =
     tailMode === "typed" ? callerMaxItems : Math.min(callerMaxItems ?? tupleLength, tupleLength);
 
@@ -533,25 +636,37 @@ function normalizeTupleBounds(
     throw new StrictifierError("tuple minItems cannot exceed maxItems", path);
   }
 
-  return {
-    minItems,
-    ...(maxItems !== undefined ? { maxItems } : {}),
-  };
+  const bounds: TupleBounds = { minItems };
+
+  if (maxItems !== undefined) bounds.maxItems = maxItems;
+
+  return bounds;
 }
 
-function integerBound(value: unknown, keyword: string, path: string): number | undefined {
+const nonNegativeSafeInteger = z
+  .number()
+  .refine((value) => Number.isSafeInteger(value) && value >= 0);
+
+function integerBound(
+  value: JsonValue | undefined,
+  keyword: string,
+  path: string,
+): number | undefined {
   if (value === undefined) return undefined;
-  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+  const bound = nonNegativeSafeInteger.safeParse(value);
+
+  if (!bound.success) {
     throw new StrictifierError(`${keyword} must be a non-negative safe integer`, path);
   }
-  return value as number;
+
+  return bound.data;
 }
 
-function isSchemaObject(value: unknown): value is JsonSchema {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function isSchemaObject(value: JsonValue | undefined): value is JsonSchema {
+  return isJsonObject(value);
 }
 
-function ownValue(schema: JsonSchema, keyword: string): unknown {
+function ownValue(schema: JsonSchema, keyword: string): JsonValue | undefined {
   return Object.hasOwn(schema, keyword) ? schema[keyword] : undefined;
 }
 
@@ -570,27 +685,38 @@ function hasProviderSchemaEntryPoint(schema: JsonSchema): boolean {
 
 function omitKeys(node: JsonSchema, keys: readonly string[]): JsonSchema {
   const omitted = new Set(keys);
+
   return Object.fromEntries(Object.entries(node).filter(([key]) => !omitted.has(key)));
 }
 
-function makeNullable(schema: JsonSchema): JsonSchema {
+function hasNullVariant(variants: JsonValue[]): boolean {
+  return variants.some(
+    (variant) => isSchemaObject(variant) && ownValue(variant, "type") === "null",
+  );
+}
+
+function makeNullable(schema: JsonValue): JsonValue {
+  const nullSchema: JsonSchema = { type: "null" };
+
+  if (!isSchemaObject(schema)) return { anyOf: [schema, nullSchema] };
+
   if (ownValue(schema, "type") === "null") return schema;
 
   const anyOf = ownValue(schema, "anyOf");
+
   if (anyOf) {
-    const variants = anyOf as JsonSchema[];
-    const hasNull = variants.some((v) => ownValue(v, "type") === "null");
-    if (hasNull) return schema;
-    return { anyOf: [...variants, { type: "null" }] };
+    if (!Array.isArray(anyOf)) throw new StrictifierError("anyOf must be an array of schemas", "$");
+
+    return hasNullVariant(anyOf) ? schema : { anyOf: [...anyOf, nullSchema] };
   }
 
   const oneOf = ownValue(schema, "oneOf");
+
   if (oneOf) {
-    const variants = oneOf as JsonSchema[];
-    const hasNull = variants.some((v) => ownValue(v, "type") === "null");
-    if (hasNull) return schema;
-    return { oneOf: [...variants, { type: "null" }] };
+    if (!Array.isArray(oneOf)) throw new StrictifierError("oneOf must be an array of schemas", "$");
+
+    return hasNullVariant(oneOf) ? schema : { oneOf: [...oneOf, nullSchema] };
   }
 
-  return { anyOf: [schema, { type: "null" }] };
+  return { anyOf: [schema, nullSchema] };
 }

package/bundle/src/utils/providers/common/thinking.ts

@@ -1,10 +1,10 @@
 import { BadRequestException } from "sonamu";
 
-import { type LocalizedString } from "../../../i18n/sd.generated";
+import { SD } from "../../../i18n/sd.generated";
 
 export class ThinkingValidationError extends BadRequestException {
   constructor(message: string) {
-    super(message as LocalizedString);
+    super(SD("error.detail")(message));
     this.name = "ThinkingValidationError";
   }
 }

package/bundle/src/utils/providers/common/ttft.ts

@@ -1,9 +1,11 @@
-export function createTtftTracker(now: () => number = Date.now): {
+export interface TtftTracker {
   markStart: () => void;
   recordFirstDelta: () => void;
   value: () => number | null;
   wrapDelta: (onDelta: (text: string) => void) => (text: string) => void;
-} {
+}
+
+export function createTtftTracker(now: () => number = Date.now): TtftTracker {
   let startedAt: number | null = null;
   let ttftMs: number | null = null;