fix: align structured output readers with Sorbet types

[jbeckwith-oai]

Summary

Fix the contract mismatch between the Tapioca structured-output compiler introduced in #364 and the raw-value compatibility rollback in #375.

• Materialize typed readers only for application-defined OpenAI::BaseModel structured-output classes.
• Keep caller-owned hashes and arrays untouched in [] and to_h, including on directly constructed and reassigned structured-output models.
• Preserve already-materialized parsed-response values, including nullable array identity, and retain precise nested model, array, union, enum, boolean, and nullable Sorbet signatures.
• Fix the root cause of recursive Symbol failures once in the SDK-owned primitive converter; String → Symbol now works naturally through arbitrary arrays, unions, and nested models without structured-output-specific normalization branches.
• Discard stale errors from viable structured-output union branches, honor explicitly assigned nullable values before inherited converter-error checks, and reject missing/non-nullable nil, non-viable boolean, enum, and mutated-container values with OpenAI::Errors::ConversionError instead of violating generated reader types.
• Verify the original customer-facing message.parsed workflow from Beta Feedback and Feature Requests! #126/Provide supported Sorbet/Tapioca typing for user-defined structured-output models #309 and the Responses content.parsed workflow through real public client calls.
• Add a cross-boundary contract matrix that checks generated RBIs against actual construction, assignment, and parsed-response behavior.

Why existing tests did not catch this

1. fix: coerce nested BaseModel fields #295 had already enabled global nested coercion when feat: add Tapioca typing for structured outputs #364 introduced the Tapioca compiler, so concrete nested signatures matched the then-current behavior.
2. The compiler regression generated RBI text and ran Sorbet against a synthetic parsed value, but never instantiated the models or compared runtime reader values to those signatures.
3. revert: nested BaseModel coercion (#295) #375 reverted global coercion and added strong raw-value compatibility tests for generated/internal request models and parsed API models, but did not exercise application-defined structured-output models or the Tapioca compiler contract.
4. Existing structured-output streaming tests used scalar-only models, so neither nested readers nor nested array elements exposed the mismatch.
5. The primitive converter matrix tested literal Symbol constants but never tested Symbol as a class target, even though structured-output schemas explicitly advertise Symbol; successive container-specific fixes therefore masked the missing canonical scalar behavior.

The new compiler test closes the gap by checking every advertised field shape against runtime readers for direct construction, explicit assignment, and parsed responses in the same subprocess that generates and typechecks the RBI. It additionally checks raw identity through both accessors, nullable array elements and parsed array identity, direct/nested Symbol arrays and unions, including Symbol-bearing models inside arrays and unions, enum conversion, both union branches, nested model inheritance, caller-owned mutations, and conversion errors for invalid booleans, enums, and nested container values.

A 108-assertion scalar/container matrix systematically combines every supported scalar (String, Symbol, Integer, Float, boolean, enum) with nested model, array, and union boundaries across construction, assignment, and parsed conversion. Public-client integration tests exercise both chat.completions.create(response_format: Model) and responses.create(text: Model) using Minitest's stub on the SDK's actual HTTP-client protocol. Primitive-converter regressions separately verify valid Symbols, JSON strings, invalid input, and exactness/error accounting. A separate nine-shape nullable matrix verifies explicitly constructed, assigned, and parsed nil across String, Symbol, Integer, Float, Boolean, model, array, enum, and union readers; the generated-RBI subprocess independently checks nullable constructor and assignment behavior.

Design tradeoff

Globally restoring nested coercion would regress the published generated-request model contract. Widening generated readers to model/hash unions would make signatures truthful but would also require narrowing every nested field in normal parsed-response code. Documenting the signatures as parsed-only would leave direct construction and assignment unsound.

Instead, the structured-output subclass prepends one small reader module per application-defined model. Each wrapper delegates to the original generated reader for existing validation, returns already-materialized values unchanged, and uses the existing canonical converter only when the raw value does not already match its declared target. Raw storage remains unchanged, and generated SDK request models never enter this path.

Symbol conversion belongs alongside the converter's existing String, Integer, and Float primitive branches, not in separate model/array/union pre-processing hooks. Fixing that canonical scalar branch deletes 41 lines of workaround logic and automatically handles every recursive composition. An audit of all 2,308 generated/internal model classes found zero direct Symbol declarations, and the generated-request raw-value compatibility suite remains unchanged and green. This changes scalar parsing only; it does not restore global nested-model coercion.

Setters are intentionally not added to generated RBIs: the documented compiler contract promises readers.

Castiron ownership

No upstream Castiron compiler or renderer change is required.

The SDK contributor guide explicitly says the generator never modifies lib/openai/helpers/. Castiron's authoritative generated-file-excludes.yaml independently excludes README.md globally, both lib/openai/helpers/ and lib/openai/internal/ for Ruby, and the handwritten test/ tree except generated resource tests and namespace scaffolding. I evaluated that policy against every changed PR path:

EXCLUDED README.md
EXCLUDED lib/openai/helpers/structured_output/base_model.rb
EXCLUDED lib/openai/helpers/structured_output/array_of.rb
EXCLUDED lib/openai/helpers/structured_output/union_of.rb
EXCLUDED lib/openai/internal/type/converter.rb
EXCLUDED test/openai/helpers/structured_output_test.rb
EXCLUDED test/openai/internal/type/base_model_test.rb
EXCLUDED test/openai/tapioca/base_model_compiler_test.rb

Castiron's Ruby renderer generates package/client/model/resource/signature files and resource tests; it does not emit the handwritten structured-output helper or these tests. The existing Tapioca compiler file is unchanged.

Verification

• mise exec ruby@4.0.6 -- env TEST_API_BASE_URL=http://127.0.0.1:4520 ./scripts/test — 648 runs, 2,813 assertions.
• mise exec ruby@3.4.10 -- env TEST_API_BASE_URL=http://127.0.0.1:4520 ./scripts/test — 648 runs, 2,813 assertions.
• mise exec ruby@3.3.12 -- env TEST_API_BASE_URL=http://127.0.0.1:4520 ./scripts/test — 648 runs, 2,813 assertions.
• mise exec ruby@4.0.6 -- bundle exec rake lint on current main — 1,389 RuboCop files clean, Sorbet clean, and 1,212 RBS files valid.
• Expanded Tapioca compiler/runtime contract regression passes on Ruby 3.3, 3.4, and 4.0.
• Existing raw-value compatibility suite remains green.
• mise exec ruby@4.0.6 -- bundle exec rake build:gem; package contains the handwritten structured-output runtime and compiler with no sorbet-runtime runtime dependency.
• Required thermo-nuclear code-quality review repeated with no findings.

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 9.728s for Ruby SDK PR #385.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	227ms
tests/chat-completions-create.test.ts	✅ Passed	309ms
tests/chat-completions-stream.test.ts	✅ Passed	125ms
tests/files-content-binary.test.ts	✅ Passed	308ms
tests/files-create-multipart.test.ts	✅ Passed	218ms
tests/files-list-pagination.test.ts	✅ Passed	171ms
tests/initialize-config.test.ts	✅ Passed	146ms
tests/instance-isolation.test.ts	✅ Passed	191ms
tests/models-list.test.ts	✅ Passed	162ms
tests/responses-background-lifecycle.test.ts	✅ Passed	178ms
tests/responses-body-method-errors.test.ts	✅ Passed	546ms
tests/responses-cancel-timeout.test.ts	✅ Passed	334ms
tests/responses-cancel.test.ts	✅ Passed	304ms
tests/responses-compact-retries.test.ts	✅ Passed	324ms
tests/responses-compact.test.ts	✅ Passed	417ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	155ms
tests/responses-create-advanced.test.ts	✅ Passed	240ms
tests/responses-create-disconnect.test.ts	✅ Passed	151ms
tests/responses-create-errors.test.ts	✅ Passed	545ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	128ms
tests/responses-create-retries.test.ts	✅ Passed	326ms
tests/responses-create-stream-failures.test.ts	✅ Passed	132ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	216ms
tests/responses-create-stream-wire.test.ts	✅ Passed	2.029s
tests/responses-create-stream.test.ts	✅ Passed	157ms
tests/responses-create-terminal-states.test.ts	✅ Passed	365ms
tests/responses-create-timeout.test.ts	✅ Passed	302ms
tests/responses-create.test.ts	✅ Passed	362ms
tests/responses-delete.test.ts	✅ Passed	262ms
tests/responses-input-items-errors.test.ts	✅ Passed	229ms
tests/responses-input-items-list.test.ts	✅ Passed	231ms
tests/responses-input-items-options.test.ts	✅ Passed	239ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	366ms
tests/responses-input-tokens-count.test.ts	✅ Passed	220ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.074s
tests/responses-not-found-errors.test.ts	✅ Passed	415ms
tests/responses-parse.test.ts	✅ Passed	270ms
tests/responses-retrieve-retries.test.ts	✅ Passed	236ms
tests/responses-retrieve.test.ts	✅ Passed	272ms
tests/responses-stored-method-errors.test.ts	✅ Passed	1.039s
tests/retry-behavior.test.ts	✅ Passed	1.896s
tests/sdk-error-shape.test.ts	✅ Passed	551ms

View OkTest run #31736547160

_{SDK merge (c97645e330d6) · head (d52773283fdc) · base (0531498c5498) · OkTest (a845fa206fa4)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1290cf5e9d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HAYDEN-OAI]

Reviewed e01f430b4572b8eeebf5d64ac3625dd5f0a0b9c0. I found two remaining reader-contract gaps in the new wrapper; details are inline. I also agree with the existing unresolved @api private documentation note.

[HAYDEN-OAI]

Re-reviewed the new head 2bebdfda62cdece88e476bb831f1028bd402b264. The previous conversion-viability, nullable-array identity, and private-API findings are addressed. One remaining non-nil reader-contract gap is inline.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bebdfda62

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bc0c6a1647

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HAYDEN-OAI]

Re-reviewed current head bc0c6a1. The required-nil and stale-union-error fixes address their reported cases. One remaining recursive Symbol-normalization gap is inline.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9ad3490c5b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HAYDEN-OAI]

Re-reviewed current head 9ad3490. Direct Symbol arrays and unions are fixed, but one remaining model-boundary recursion gap is inline.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b592d72ccc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".