feat(reborn): add OpenAI-compatible API contracts

[hanakannzashi]

Summary

• Added a new ironclaw_reborn_openai_compat crate for Reborn OpenAI-compatible Chat Completions and Responses API ingress contracts.
• Declared host-owned route descriptors for chat completions plus Responses create/retrieve/cancel routes, with fail-closed beta router stubs until ProductWorkflow wiring lands.
• Added stable UI/client-safe OpenAI-compatible error envelopes and DTO contract coverage for chat, responses, and streaming shapes.
• Added architecture guardrails and Reborn contract docs so this slice cannot bind listeners, route through v1 gateway paths, or bypass ProductWorkflow/projection boundaries.

Change Type

• Bug fix
• New feature
• Refactor
• Documentation
• CI/Infrastructure
• Security
• Dependencies

Linked Issue

Closes #4442

Validation

• cargo fmt --all -- --check
• cargo clippy --all --benches --tests --examples --all-features -- -D warnings
• cargo build
• Relevant tests pass: cargo test -p ironclaw_reborn_openai_compat, cargo test -p ironclaw_reborn_openai_compat --features openai-compat-beta, cargo test -p ironclaw_architecture
• cargo test --features integration if database-backed or integration behavior changed
• Manual testing: Not applicable; this is a contract/stub slice with fail-closed route handlers.
• If a coding agent was used and supports it, review-pr or pr-shepherd --fix was run before requesting review

Additional validation:

• cargo clippy -p ironclaw_reborn_openai_compat --all-targets --all-features -- -D warnings
• git diff --check

Security Impact

Yes. This defines Reborn OpenAI-compatible ingress contracts and route policies, but does not bind sockets or enable runtime traffic. Descriptors require host-owned LocalGateway bearer-token ingress, ProductWorkflow/projection effect paths, host-configured CORS, body/rate limits, and no direct v1 gateway or LLM proxy path. Error tests assert backend details, paths, and secret-like values do not serialize through the compatibility error envelope.

Database Impact

None.

Blast Radius

Limited to the new ironclaw_reborn_openai_compat crate, Reborn contract docs, workspace membership, and architecture guardrails. No existing route, listener, database, runtime, or v1 gateway behavior changes.

Rollback Plan

Revert this PR to remove the OpenAI-compatible contract crate, route descriptors, docs, and architecture guardrail additions. Since no listener/runtime path is wired, rollback should not require data migration or runtime cleanup.

Review Follow-Through

Reviewer judgment requested on the exact route set (/v1/* and /api/v1/* aliases), the OpenAI-compatible DTO surface to freeze in this first contract slice, and whether the beta router stubs should remain feature-gated until ProductWorkflow wiring lands.

---

Review track: C

[gemini-code-assist]

Code Review

This pull request introduces the ironclaw_reborn_openai_compat crate, establishing a Reborn-native OpenAI-compatible API contract surface with Chat Completions and Responses DTOs, route descriptors, and fail-closed route fragments. Feedback focuses on improving type safety by refactoring OpenAiResponsesInputItem and OpenAiResponseOutputItem from structs with optional fields into internally-tagged enums. Additionally, it is recommended to map all HTTP 5xx errors to a single status code (such as 503) in sanitize_status_code to ensure consistent recovery semantics.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[serrrfirat]

Code Review

Reviewed PR #4459 at 035a2655122c73607cf7f0e15e033f6221e3039f with security, bugs, performance/concurrency, tests, and conventions passes. No Critical or High findings. I found 7 Medium findings: 2 security/contract sanitization risks, 3 API contract mismatches, and 2 focused coverage gaps.

Validation run during review: cargo test -p ironclaw_reborn_openai_compat --features openai-compat-beta passed.

[abbyshekit]

Code review — feat(reborn): add OpenAI-compatible API contracts

Multi-agent review (security · bugs · performance · tests · conventions) at 035a2655. Diff-only mode.

Independent review of an open PR.

5 findings — 4 Medium, 1 Low. Posted as a comment (advisory). Confidence ≥ 50, deduplicated across reviewers.

Sev	Conf	Reviewer	Location	Finding
Medium	90%	conventions	openai-compatible-api.md:73	Contract docs claim stub returns 501, but code/test return 503
Medium	80%	bugs	error.rs:160	Non-retryable 500 internal errors are emitted as HTTP 503 (retryable), contradicting their own error code and retryable flag
Medium	80%	tests	error_contract.rs:1	5 of 7 ProductWorkflowRejectionKind mapping arms are never exercised
Medium	78%	bugs	error.rs:119	Fail-closed stub returns HTTP 503, not the 501 documented across the crate's contracts
Low	62%	tests	dto_contract.rs:1	No test that requests missing required fields (model/messages/input) deserialize to a clean Err

---

_{Generated by near-ai-code-review (5 parallel reviewer agents + intent analysis). Diff-only; confidence ≥ 50; ≤ 15 inline comments.}

[serrrfirat]

@hanakannzashi lets fix themerge conflicts and merge this