test(ai): disposition tables + one fidelity corpus for the three tool-schema translators (design #1684, phase 1) #1685

Phase 1 of design #1684 — disposition tables + one fidelity corpus for the three schema translators

Design #1684 (doc: files/designs/opencode-schema-projection-fidelity.md in the keep-the-four-repos-healthy goal workspace) states one fidelity contract for the provider tool-schema projections in packages/ai: every keyword, in every translator, has exactly one named disposition — preserved, approximated (named, with direction: widening or narrowing), or refused — and never silent, never inverted, never contradicted. This phase builds the contract's enforcement artifact: the tables and the corpus that asserts them. No production behaviour changes.

Scope

• Disposition tables for the three translators, checked in where their tests live (a table fixture/module the corpus consumes — name per repo convention):
  • antigravity convertSchema/convertSchemaNode (packages/ai/src/protocols/antigravity.ts),
  • GeminiJsonSchema.normalize (packages/ai/src/protocols/utils/gemini-json-schema.ts),
  • ToolSchemaProjection.moonshot (packages/ai/src/protocols/utils/tool-schema.ts).
• Each table covers: every keyword appearing in the repo's built-in tool schemas, plus every keyword shape exercised by the family fixes Antigravity door: tool-carrying sessions 400 on function_declarations schema (paths.items missing field) #1548/Antigravity door: Claude leaf (claude-sonnet-5-5) 400s on workhorse attempts, Anthropic-shaped error #1550/fix(ai): antigravity convertSchema collapses a multi-valued type union to its first member — type: ["string","integer"] is sent upstream as STRING only #1556/fix(ai): antigravity convertSchema inverts boolean false subschemas — a never-valid schema is sent upstream as unconstrained #1573/fix(ai): Gemini schema normalize only cuts single-def $ref loops — mutually recursive $defs through required properties reach Gemini uncut #1585/fix(ai): antigravity convertSchema forces type OBJECT onto allOf/not-only roots — a string allOf root becomes unsatisfiable, a not root is narrowed to objects #1667 (boolean subschemas, multi-valued type, allOf/not-only roots, ARRAY without items, mutually recursive $defs, draft-04 bounds, draft-07 tuples).
• One shared corpus in packages/ai/test/ (extending or alongside the existing per-translator suites tool-schema-projection.test.ts, gemini-json-schema.test.ts, provider/antigravity.test.ts): every table row runs through its translator and the projected shape is asserted against the table. The oracle is the table itself (the model of each translator's intended semantics) — name it as such in the test file's header comment.
• Rows whose current behaviour is known-lossy are recorded in the table as known-lossy and linked: antigravity const → fix(ai): antigravity convertSchema drops const — a fixed-value parameter is sent upstream unconstrained #1557 (open), Moonshot prefixItems with items present → fix(ai): moonshot tool-schema projection drops prefixItems when items is also present — position constraints are silently replaced #1574 (open). The corpus asserts the table including those rows' current projected shapes, so each site's fix flips exactly one row to its conforming disposition.
• Approximations that already exist and were probed against live endpoints are recorded as named approximations, not changed: Gemini loop-cut to {} (fix(ai): Gemini schema normalize only cuts single-def $ref loops — mutually recursive $defs through required properties reach Gemini uncut #1585's cutDefCycles semantics), antigravity anyOf→oneOf fold for Anthropic targets (Antigravity door: Claude leaf (claude-sonnet-5-5) 400s on workhorse attempts, Anthropic-shaped error #1550), Moonshot prefixItems fold when items is absent, objectRoot's object-root forcing in tool-schema.ts.

Out of scope

• Any change to translator production code (the fix(ai): antigravity convertSchema drops const — a fixed-value parameter is sent upstream unconstrained #1557/fix(ai): moonshot tool-schema projection drops prefixItems when items is also present — position constraints are silently replaced #1574 fixes are those issues' own work, adopted as design design(ai): translate the constraint, or say so — one fidelity contract for provider tool-schema projections #1684 phase 2).
• Built-in-schema meta-validation (test(ai,core): meta-validate every built-in tool schema against the draft 2020-12 meta-schema after Anthropic translation — #1550's offender is still unnamed #1668, design phase 3, its own lifecycle).
• Other protocol schema paths (bedrock, OpenAI-compatible, gateway sanitizers) — design phase 4, deliberately unfiled.

Acceptance

• A disposition table exists for each of the three named translators, covering the keyword set above, with every row one of preserved / approximated-named-with-direction / refused / known-lossy-with-issue-link.
• The shared corpus runs every table row through its translator and passes on current main, with known-lossy rows asserted as their current (lossy) projections and clearly marked.
• The corpus fails if a translator's projection for a table keyword changes without the table changing (spot-provable by flipping one row in review).
• No production files under packages/ai/src/ change.
• Existing ai suites still pass: bun test for packages/ai/test/tool-schema-projection.test.ts, gemini-json-schema.test.ts, and provider/antigravity.test.ts (via CI per fleet policy).

🤖 Agent note · state: filed

• Agent: repo-design-architect job (opencode pass)
• Session / ID: cron repo-design-architect, run 2026-11-04 19:33 CST
• Found via: design pass on developing-today-forks/opencode, main 618de2888f
• Task: Phase 1 of design design(ai): translate the constraint, or say so — one fidelity contract for provider tool-schema projections #1684 — disposition tables + shared fidelity corpus for the three packages/ai schema translators; tests/tables only.
• Expectation: done when the acceptance boxes above hold on the PR that closes this issue; the two known-lossy rows (fix(ai): antigravity convertSchema drops const — a fixed-value parameter is sent upstream unconstrained #1557, fix(ai): moonshot tool-schema projection drops prefixItems when items is also present — position constraints are silently replaced #1574) are asserted as current behaviour and flip when those issues land.
• Links: design design(ai): translate the constraint, or say so — one fidelity contract for provider tool-schema projections #1684; design doc files/designs/opencode-schema-projection-fidelity.md (keep-the-four-repos-healthy goal workspace); queue packet enqueued to repo-health-opencode-pilot this run.