chore: enforce generated-file ownership

.castiron.stats.yml

@@ -1,8 +1,7 @@
 schema_version: 1
-generation_id: 68bd942a-6d9f-44d3-8c8b-46ae55d85e50
+generation_id: 9e3623b2-d4e0-44b9-907b-93835ac5946a
 openapi_spec_hash: 3273c8e0a3c60aa72222e3b5970513fd
 openapi_transformed_spec_hash: da0a1022fdcb8ba16fe3417d9b670a6d
 config_hash: 8a39abf288ab81f39720996b7bfd990a
-codegen_sha: 3e9a4b126b6d25d5776122bb165289701c36e63d
-codegen_hash: cc631164dc74d37b508a404ddfb80481610c613607a383bfc941836918e2d22c
-public_codegen_sha: eeb7c1db53408f178c5b8c63a027b112d47fcd59
+codegen_sha: 72c32974dfdec5fd9be954a92a4aaca7fd9ba0fc
+codegen_hash: 5bbc3afa0a60dc7f537bb2553a476ae5438ff0f0e1e61b6feb54ee69f0a0268c

AGENTS.md

@@ -7,15 +7,21 @@ generator owns the code you are changing, preserve existing generated behavior,
 authoritative source when it is available. The `openai-java-example/` directory is not modified by
 the generator.
 
-## Custom-code budget
+## Generated-file ownership
 
-Follow [the custom-code guidance](scripts/castiron/CUSTOM_CODE.md). Budget changes
-belong in a separate PR containing only `.castiron-ratchet.json`, with an explicit justification
-in the PR description. Increases require a **human approving review** before merging.
-Agents may investigate and draft proposals, but must not approve budget increases
-(including through a human's credentials) or bypass the gate. Do not weaken
-counting, broaden exclusions, or alter generation metadata to make a change pass.
-The checker and effective budget come from main, not the PR. Keep default CODEOWNERS.
+Never hand-edit generated SDK files, including generated tests, documentation,
+workflows, or the generated-file inventory. Change the authoritative API schema,
+configuration, or compiler, then regenerate. Put SDK-specific behavior in
+separately owned handwritten helpers and extension points.
+
+Regeneration replaces generator-owned files and deletes retired generated paths.
+Handwritten edits to generated files are overwritten; they are never replayed or
+merged into new output. Preserve separately owned handwritten files and resolve
+ownership collisions explicitly. Follow this AGENTS.md rule and review generated output and inventory changes
+together. Generated-file ownership currently relies on contributor guidance and
+code review; there is no dedicated generated-file edit check or required gate.
+Fix violations in the inputs/compiler and regenerate; never update inventory
+hashes to accept a handwritten patch.
 
 ## Security requirements
 

CONTRIBUTING.md

@@ -24,22 +24,21 @@ management. The framework-neutral SDK requires Java 8, while development require
 Kotlin toolchain. See the [Java version support policy](docs/version-support-policy.md) for
 artifact-level runtime, framework, lifecycle, and release rules.
 
-## Custom-code budget
-
-The custom-code budget counts additions plus deletions in the remaining patch
-against verified generated output. `.castiron-ratchet.json` defines this repository's
-ceiling. CI uses the checker and budget on main, not the PR's proposed versions.
-
-Budget changes must be in a separate PR modifying **only `.castiron-ratchet.json`**.
-Justify the current usage, proposed ceiling, and why fixing generation is not
-appropriate in the PR description. Increases require a **human approving review**
-and must merge before an SDK change relies on them. Agents may draft proposals,
-but must not approve increases or bypass the gate. Keep default CODEOWNERS.
-Lower the ceiling after cleanup while retaining headroom; decreases must still
-fit the measured usage.
-
-See [custom-code technical details](scripts/castiron/CUSTOM_CODE.md) for accounting,
-local checks, trusted CI, and activation instructions.
+## Generated-file ownership
+
+Do not edit generated SDK files by hand. Fix the API schema, generation
+configuration, or compiler and regenerate instead. Put SDK-specific behavior in
+separately owned handwritten helpers and extension points.
+
+Regeneration replaces generated files and removes retired generated paths.
+Handwritten edits to generated output are overwritten, not carried forward.
+Separately owned handwritten files are preserved. Resolve ownership conflicts
+explicitly before regeneration. Follow the ownership rules in `AGENTS.md`
+and review generated output and inventory changes together. Generated-file
+ownership currently relies on contributor guidance and code review, without a
+dedicated generated-file edit check or required gate. Fix violations in the
+generation inputs/compiler and regenerate; do not edit inventory hashes to
+accept a handwritten patch.
 
 ## Security expectations
 
@@ -90,8 +89,8 @@ artifact's eligibility on a given JVM come from `gradle/version-support.properti
 
 ## Modifying or adding code
 
-Most of the SDK is generated code. Modifications to code will be persisted between generations, but may
-result in merge conflicts between manual patches and changes from the generator. The generator will never
+Most of the SDK is generated code. Never edit generated files by hand; change
+the authoritative generation inputs or compiler and regenerate instead. The generator will never
 modify the contents of the `openai-java-example/` directory.
 
 ## Adding and running examples

docs/architecture/security-model.md

@@ -1,11 +1,21 @@
 # OpenAI Java SDK security model
 
+Generated files are updated through authoritative inputs or the compiler and
+regeneration; handwritten edits to them are forbidden. Code review enforces this
+ownership rule. The customization-budget reporter and publishers are retired
+and are not part of the active CI or security controls.
+
 This is the repository's single canonical detailed threat model. Use it for
 security review and Codex Security scans of the revision being reviewed.
 SECURITY.md remains the authority for private disclosure and reportability
 instructions; this document is the authority for architecture, trust boundaries,
 attacker capabilities, security objectives, and severity calibration.
 
+Generated-file ownership currently relies on `AGENTS.md`, contributor guidance,
+and ordinary SDK code review. There is no dedicated generated-file edit check or
+required gate. Review generated output and inventory changes together; fix
+violations in the inputs/compiler and regenerate.
+
 ## Overview
 
 This repository publishes Java/Kotlin client libraries rather than a hosted
@@ -106,13 +116,10 @@ not exposed to the attestation action.
   boundary where independently mutable data enters a parser/evaluator, where
   runtime/network data reaches a sensitive sink, or where PR-controlled code can
   reach protected CI or release credentials.
-- Candidate Git objects can still be lower-trust data when a separately
-  privileged workflow evaluates them. The workflow_run custom-code workflow
-  checks out trusted main, computes from current PR Git objects, and freshness
-  checks the exact head before publishing status; breaking that evaluator boundary
-  remains a security finding. (.github/workflows/castiron-custom-code-comment.yml:34-57;
-  .github/workflows/castiron-custom-code-comment.yml:74-98;
-  .github/workflows/castiron-custom-code-comment.yml:128-181)
+- Candidate Git objects remain lower-trust data when a separately privileged
+  evaluator handles them. Such an evaluator must independently constrain that
+  data before accessing protected CI or release authority.
+
 - Merged, reviewed repository source intentionally executes with trusted
   build/release authority. The security boundary is externally enforced branch
   governance, CODEOWNERS/rulesets, verified release selection, and protected
@@ -171,7 +178,6 @@ These are review hypotheses, not confirmed findings.
 | High | Untrusted webhook bytes are parsed or acted on without valid signature/freshness checks. | Embedding application exposes webhook ingress and relies on SDK verification. | Forged event acceptance. | Required headers, bounded timestamp tolerance, HMAC-SHA256, timing-safe compare, then parse; no replay deduplication. | Preserve verify-before-parse ordering and focused regression tests; embedding applications must deduplicate accepted webhook IDs when replay matters. | openai-java-core/src/main/kotlin/com/openai/services/WebhookVerification.kt:19-99; openai-java-core/src/main/kotlin/com/openai/services/blocking/WebhookServiceImpl.kt:33-41 |
 | Medium | Independently mutable API/SSE JSON crosses a parser boundary and causes unsafe interpretation, resource exhaustion, or sensitive exception/log output. | Attacker controls an API/network response or configured proxy; sink is reachable in caller deployment. | Client failure, data exposure, or downstream misuse. | Strict mapper defaults, typed parsing, stream iteration, and explicit DEBUG diagnostics. | Keep parsing robust and large-payload-compatible; avoid treating model output as executable authority without caller controls. | openai-java-core/src/main/kotlin/com/openai/core/ObjectMappers.kt:34-116; openai-java-core/src/main/kotlin/com/openai/core/handlers/SseHandler.kt:19-60; AGENTS.md:49-66 |
 | Medium | Credentials or customer payloads reach an unintended destination or uncontrolled log. | Lower-trust actor independently controls base URL/proxy/TLS/log sink, or diagnostics are enabled in an unsafe deployment. | Secret or customer-data disclosure. | Production URL default, caller-owned configuration, auth wrappers, and default sensitive-header redaction; DEBUG is explicit. | Preserve redaction and destination/TLS controls; document caller obligations. | openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:151-172; openai-java-core/src/main/kotlin/com/openai/core/ClientOptions.kt:601-665; openai-java-core/src/main/kotlin/com/openai/core/http/LoggingHttpClient.kt:24-48; openai-java-core/src/main/kotlin/com/openai/core/http/LoggingHttpClient.kt:91-142 |
-| Medium | A separately privileged evaluator consumes mutable PR Git objects, artifacts, or cache entries as trusted code/data. | Privileged workflow reads candidate state without binding/ref validation. | Privilege crossing beyond ordinary PR CI. | Custom-code workflow checks out main, uses current PR objects, and freshness-checks exact head; PR cache scope remains isolated. | Preserve trusted checkout and exact-head/digest binding. | .github/workflows/castiron-custom-code-comment.yml:34-57; .github/workflows/castiron-custom-code-comment.yml:128-181; .github/workflows/ci.yml:120-129 |
 | Low / not a boundary by itself | A PR changes a checked-in example, test, fixture, build script, or generated source and ordinary PR CI executes it. | The same PR author already controls the tracked executable checkout. | No new capability beyond the unprivileged PR job. | PR CI has read-only contents and no release credentials; cache scope is enforced outside PR code. | Investigate only if execution crosses an independent input or protected-authority boundary. | .github/workflows/ci.yml:8-20; .github/workflows/ci.yml:33-48; .github/workflows/ci.yml:92-107 |
 
 ## Severity calibration (critical, high, medium, low)