test: support hermetic local API reference

[apcha-oai]

Allow the SDK mock server to use a locally available API reference when present, while preserving the existing network-based fallback.

[Copilot]

Pull request overview

This PR updates the scripts/mock helper to prefer a locally available, generated OpenAPI reference (when present) for starting the SDK mock server, while keeping the existing URL-based behavior as a fallback.

Changes:

• Add detection of a local transformed OpenAPI spec (api_reference/openapi.transformed.yml) plus generation metadata (.castiron.stats.yml).
• Validate the local spec against the expected hash before using it.
• Preserve the existing behavior of reading openapi_spec_url from .stats.yml when no local reference is available.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jbeckwith-oai]

Thermo-nuclear code-quality review: no high-confidence maintainability findings. The change keeps local-spec selection and validation together in the existing flow; scripts/mock remains 61 lines and no file approaches the 1,000-line threshold. Approved.

[HAYDEN-OAI]

Reviewed this exact head against the Castiron checked-in API-reference and metadata contracts, source-checkout test invocation, existing network fallback, and gem packaging. Found one P1 contract mismatch that prevents the proposed hermetic-local-reference path from working; details and fix direction are inline. Reproduced both failure modes and confirmed the explicit-argument and legacy-fallback behavior with seven isolated focused checks.

[HAYDEN-OAI]

[P1] Consume the actual Castiron local-reference contract. The Castiron producer checks in .castiron/api-definition.yaml and .castiron/generation-inputs.json; the descriptor's api_reference records the canonical repo-relative path and a SHA-256 hash. See https://github.com/openai/openai/blob/23bc2f67b559457998cb0facddccb8b9763ed9f4/api/sdk-worker/sdk_worker/api_ref_artifacts/castiron_repo_inputs.py#L16-L20 and https://github.com/openai/openai/blob/23bc2f67b559457998cb0facddccb8b9763ed9f4/api/sdk-worker/sdk_worker/api_ref_artifacts/castiron_repo_inputs.py#L175-L206. .castiron.stats.yml has only schema_version, generation_id, openapi_spec_hash, config_hash, and codegen_sha; its parser explicitly rejects additional fields, so openapi_transformed_spec_hash cannot be added to make this work: https://github.com/openai/openai/blob/23bc2f67b559457998cb0facddccb8b9763ed9f4/api/sdk-worker/sdk_worker/api_ref_artifacts/castiron_candidate_flow.py#L106-L133. Consequently, a real generated checkout never enters this branch and instead downloads the stale/network spec, breaking offline hermetic runs; if api_reference/openapi.transformed.yml is present alongside valid Castiron stats, EXPECTED_HASH is always empty and scripts/mock/scripts/test exit before starting Steady. I reproduced both behaviors against this exact script. Please discover the API reference from .castiron/generation-inputs.json, require its canonical .castiron/api-definition.yaml path, verify the descriptor's SHA-256 against the file, and preserve the existing .stats.yml URL fallback only when no checked-in Castiron reference is present.

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 8.16s for Ruby SDK PR #316.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	188ms
tests/chat-completions-create.test.ts	✅ Passed	206ms
tests/chat-completions-stream.test.ts	✅ Passed	125ms
tests/files-content-binary.test.ts	✅ Passed	227ms
tests/files-create-multipart.test.ts	✅ Passed	204ms
tests/files-list-pagination.test.ts	✅ Passed	193ms
tests/initialize-config.test.ts	✅ Passed	197ms
tests/instance-isolation.test.ts	✅ Passed	161ms
tests/models-list.test.ts	✅ Passed	151ms
tests/responses-background-lifecycle.test.ts	✅ Passed	211ms
tests/responses-body-method-errors.test.ts	✅ Passed	399ms
tests/responses-cancel-timeout.test.ts	✅ Passed	197ms
tests/responses-cancel.test.ts	✅ Passed	214ms
tests/responses-compact-retries.test.ts	✅ Passed	231ms
tests/responses-compact.test.ts	✅ Passed	228ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	131ms
tests/responses-create-advanced.test.ts	✅ Passed	171ms
tests/responses-create-disconnect.test.ts	✅ Passed	138ms
tests/responses-create-errors.test.ts	✅ Passed	297ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	121ms
tests/responses-create-retries.test.ts	✅ Passed	265ms
tests/responses-create-stream-failures.test.ts	✅ Passed	116ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	203ms
tests/responses-create-stream-wire.test.ts	✅ Passed	1.835s
tests/responses-create-stream.test.ts	✅ Passed	85ms
tests/responses-create-terminal-states.test.ts	✅ Passed	287ms
tests/responses-create-timeout.test.ts	✅ Passed	188ms
tests/responses-create.test.ts	✅ Passed	309ms
tests/responses-delete.test.ts	✅ Passed	220ms
tests/responses-input-items-errors.test.ts	✅ Passed	183ms
tests/responses-input-items-list.test.ts	✅ Passed	158ms
tests/responses-input-items-options.test.ts	✅ Passed	234ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	233ms
tests/responses-input-tokens-count.test.ts	✅ Passed	230ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.059s
tests/responses-not-found-errors.test.ts	✅ Passed	267ms
tests/responses-parse.test.ts	✅ Passed	182ms
tests/responses-retrieve-retries.test.ts	✅ Passed	296ms
tests/responses-retrieve.test.ts	✅ Passed	236ms
tests/responses-stored-method-errors.test.ts	✅ Passed	687ms
tests/retry-behavior.test.ts	✅ Passed	1.944s
tests/sdk-error-shape.test.ts	✅ Passed	405ms

View OkTest run #30287970508

_{SDK merge (2683cd1fc575) · head (a45bf11a07b6) · base (1f0a2d4a7128) · OkTest (91635c6a2723)}