Add translation-bench gold schema optionality helper

ts/packages/benchmarks/README.AUTOGEN.md

@@ -3,7 +3,7 @@
 
 <!-- AUTOGEN:DOCS:START -->
 
-<!-- AUTOGEN:DOCS:HASH:sha256=d44d146be9d637f265637a8290e184cf5485c4152b0a25777e2866945e1874ee -->
+<!-- AUTOGEN:DOCS:HASH:sha256=028c3076cf5247f35bd204e9ad449213f5e92600c0edb8dc93c4dbe3b3143f7e -->
 <!-- AUTOGEN:DOCS:SOURCE: ./README.md (hand-written documentation; this file is the AI-generated companion) -->
 
 # @typeagent/benchmarks — AI-generated documentation
@@ -45,17 +45,17 @@ _None._
 - [./src/index.ts](./src/index.ts)
 - [./src/translationBench/index.ts](./src/translationBench/index.ts)
 - [./src/translationBench/synthesizer/catalogGenerator/index.ts](./src/translationBench/synthesizer/catalogGenerator/index.ts)
+- [./src/translationBench/synthesizer/goldSchema.ts](./src/translationBench/synthesizer/goldSchema.ts)
 - [./src/translationBench/synthesizer/index.ts](./src/translationBench/synthesizer/index.ts)
 - [./src/core/model-prices.generated.json](./src/core/model-prices.generated.json)
 - [./src/core/paths.ts](./src/core/paths.ts)
 - [./src/core/prices.ts](./src/core/prices.ts)
 - [./src/core/rateLimiter.ts](./src/core/rateLimiter.ts)
 - [./src/core/tokenEstimate.ts](./src/core/tokenEstimate.ts)
-- [./src/core/types.ts](./src/core/types.ts)
-- _…and 36 more under `./src/`._
+- _…and 37 more under `./src/`._
 
 ---
 
-_Auto-generated against commit `ced33869a1369ff7c998a3517bf17bc9739a05e5` on `2026-08-13T05:25:43.204Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/benchmarks docs:verify-links` to spot-check._
+_Auto-generated against commit `ec5d9161876ae305ea1c253d6e038fa7d364fa62` on `2026-08-13T08:21:46.174Z` by `docs-generate.yml`. Links validated at that commit; the working tree may have drifted by up to 24h. Re-run `pnpm --filter @typeagent/benchmarks docs:verify-links` to spot-check._
 
 <!-- AUTOGEN:DOCS:END -->

ts/packages/benchmarks/src/translationBench/synthesizer/goldSchema.ts

@@ -0,0 +1,272 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import {
+    resolveTypeReference,
+    type ActionParamObject,
+    type SchemaType,
+} from "@typeagent/action-schema";
+
+export const TRANSLATION_BENCH_GOLD_OPTIONALITY_RULE =
+    "TypeAgent optionality is the source of truth for gold. The OpenAI tool " +
+    "JSON schema lists every property in required[] (translator convention) " +
+    "and does NOT make optional TypeAgent fields required. parameterScore / " +
+    "nonempty scores a present value; it is not a presence requirement. Omit " +
+    "optional fields the utterance does not support, including optional " +
+    "false booleans and empty arrays.";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function listGoldParameterFields(type: SchemaType): {
+    required: string[];
+    optional: string[];
+} {
+    const resolved = resolveTypeReference(type);
+    if (resolved?.type !== "object") {
+        return { required: [], optional: [] };
+    }
+    const required: string[] = [];
+    const optional: string[] = [];
+    for (const [name, field] of Object.entries(resolved.fields)) {
+        if (field.optional) {
+            optional.push(name);
+        } else {
+            required.push(name);
+        }
+    }
+    return { required, optional };
+}
+
+function requiredFieldNames(type: ActionParamObject): string[] {
+    return Object.entries(type.fields)
+        .filter(([, field]) => field.optional !== true)
+        .map(([name]) => name);
+}
+
+function rewriteNode(
+    json: unknown,
+    type: SchemaType,
+    defs: Record<string, unknown> | undefined,
+    seenDefs: Set<string>,
+): void {
+    if (!isPlainObject(json)) {
+        return;
+    }
+    if (typeof json.$ref === "string" && json.$ref.startsWith("#/$defs/")) {
+        const name = json.$ref.slice("#/$defs/".length);
+        if (
+            defs !== undefined &&
+            isPlainObject(defs[name]) &&
+            !seenDefs.has(name)
+        ) {
+            seenDefs.add(name);
+            rewriteNode(defs[name], type, defs, seenDefs);
+        }
+        return;
+    }
+    const resolved = resolveTypeReference(type) ?? type;
+    if (resolved.type === "object") {
+        json.required = requiredFieldNames(resolved);
+        const properties = json.properties;
+        if (isPlainObject(properties)) {
+            for (const [name, field] of Object.entries(resolved.fields)) {
+                if (properties[name] !== undefined) {
+                    rewriteNode(properties[name], field.type, defs, seenDefs);
+                }
+            }
+        }
+        return;
+    }
+    if (resolved.type === "array") {
+        rewriteNode(json.items, resolved.elementType, defs, seenDefs);
+        return;
+    }
+    if (resolved.type === "type-union" && Array.isArray(json.anyOf)) {
+        const variants = json.anyOf;
+        resolved.types.forEach((member, index) => {
+            rewriteNode(variants[index], member, defs, seenDefs);
+        });
+    }
+}
+
+/**
+ * Rewrite an OpenAI-style tool parameters JSON schema so `required` matches
+ * TypeAgent field.optional. generateActionActionFunctionJsonSchemas marks
+ * every property required (strict-mode convention); gold labeling must not.
+ */
+export function rewriteJsonSchemaRequiredForGold(
+    schema: Record<string, unknown>,
+    type: SchemaType,
+): Record<string, unknown> {
+    const clone = structuredClone(schema);
+    const defs = isPlainObject(clone.$defs) ? clone.$defs : undefined;
+    rewriteNode(clone, type, defs, new Set());
+    return clone;
+}
+
+export function applyGoldOptionalityToToolParameters(
+    parameters: Record<string, unknown> | undefined,
+    parameterType: SchemaType | undefined,
+): Record<string, unknown> | undefined {
+    if (parameters === undefined || parameterType === undefined) {
+        return parameters;
+    }
+    return rewriteJsonSchemaRequiredForGold(parameters, parameterType);
+}
+
+function matchingUnionObject(
+    type: SchemaType,
+    value: Record<string, unknown>,
+): ActionParamObject | undefined {
+    const resolved = resolveTypeReference(type) ?? type;
+    if (resolved.type === "object") {
+        return resolved;
+    }
+    if (resolved.type !== "type-union") {
+        return undefined;
+    }
+    const keys = Object.keys(value);
+    for (const member of resolved.types) {
+        const objectType = resolveTypeReference(member);
+        if (objectType?.type !== "object") continue;
+        if (keys.every((key) => objectType.fields[key] !== undefined)) {
+            return objectType as ActionParamObject;
+        }
+    }
+    return undefined;
+}
+
+function isOptionalBooleanField(type: ActionParamObject, key: string): boolean {
+    const field = type.fields[key];
+    if (field === undefined || !field.optional) {
+        return false;
+    }
+    const resolved = resolveTypeReference(field.type);
+    return resolved?.type === "boolean";
+}
+
+type StripResult = { kept: true; value: unknown } | { kept: false };
+
+function stripOptionalFalseArray(
+    value: unknown[],
+    type: SchemaType,
+    path: string,
+    removed: string[],
+): StripResult {
+    const resolved = resolveTypeReference(type) ?? type;
+    if (resolved.type !== "array") {
+        return { kept: true, value };
+    }
+    const next: unknown[] = [];
+    let changed = false;
+    for (let i = 0; i < value.length; i += 1) {
+        const child = stripOptionalFalseValue(
+            value[i],
+            resolved.elementType,
+            `${path}[${i}]`,
+            removed,
+        );
+        if (!child.kept) {
+            changed = true;
+            continue;
+        }
+        if (child.value !== value[i]) {
+            changed = true;
+        }
+        next.push(child.value);
+    }
+    if (next.length === 0 && value.length > 0) {
+        removed.push(path);
+        return { kept: false };
+    }
+    return { kept: true, value: changed ? next : value };
+}
+
+function stripOptionalFalseObject(
+    value: Record<string, unknown>,
+    type: SchemaType,
+    path: string,
+    removed: string[],
+): StripResult {
+    const objectType = matchingUnionObject(type, value);
+    if (objectType === undefined) {
+        return { kept: true, value };
+    }
+    const next: Record<string, unknown> = {};
+    let changed = false;
+    for (const [key, childValue] of Object.entries(value)) {
+        const childPath = path === "" ? key : `${path}.${key}`;
+        if (childValue === false && isOptionalBooleanField(objectType, key)) {
+            removed.push(childPath);
+            changed = true;
+            continue;
+        }
+        const field = objectType.fields[key];
+        if (field === undefined) {
+            next[key] = childValue;
+            continue;
+        }
+        const child = stripOptionalFalseValue(
+            childValue,
+            field.type,
+            childPath,
+            removed,
+        );
+        if (!child.kept) {
+            changed = true;
+            continue;
+        }
+        if (child.value !== childValue) {
+            changed = true;
+        }
+        next[key] = child.value;
+    }
+    if (Object.keys(next).length === 0) {
+        if (path !== "") {
+            removed.push(path);
+        }
+        return { kept: false };
+    }
+    return { kept: true, value: changed ? next : value };
+}
+
+function stripOptionalFalseValue(
+    value: unknown,
+    type: SchemaType,
+    path: string,
+    removed: string[],
+): StripResult {
+    if (Array.isArray(value)) {
+        return stripOptionalFalseArray(value, type, path, removed);
+    }
+    if (!isPlainObject(value)) {
+        return { kept: true, value };
+    }
+    return stripOptionalFalseObject(value, type, path, removed);
+}
+
+export function stripOptionalFalseGoldBooleans(
+    parameters: Record<string, unknown> | undefined,
+    type: SchemaType,
+): {
+    parameters: Record<string, unknown> | undefined;
+    removed: string[];
+} {
+    if (parameters === undefined) {
+        return { parameters: undefined, removed: [] };
+    }
+    const removed: string[] = [];
+    const stripped = stripOptionalFalseValue(parameters, type, "", removed);
+    if (!stripped.kept) {
+        return { parameters: undefined, removed };
+    }
+    if (stripped.value === parameters) {
+        return { parameters, removed: [] };
+    }
+    return {
+        parameters: stripped.value as Record<string, unknown>,
+        removed,
+    };
+}

ts/packages/benchmarks/src/translationBench/synthesizer/index.ts

@@ -18,3 +18,4 @@ export { seedQaJsonlAdapter } from "./adapters/seedQaJsonlAdapter.js";
 export * from "./emptyGoldUtterance.js";
 export * from "./goldParameterHygiene.js";
 export * from "./actionValidation.js";
+export * from "./goldSchema.js";