feat(reborn): add OpenAI-compatible product refs

[hanakannzashi]

Summary

• Added typed opaque OpenAI-compatible public refs (chatcmpl-*, resp_*) plus actor-scoped internal ProductWorkflow/projection ref mappings.
• Added OpenAiCompatRefStore with in-memory and filesystem-backed durable adapters for idempotency replay/conflict, bind, lookup, stream-resume, and cancel authorization semantics.
• Added fail-closed validation for malformed refs, inconsistent public-id/surface mappings, corrupt persisted state, cross-actor lookup/bind non-leakage, and sanitized ref-store errors.
• Documented the OpenAI-compatible ref/idempotency contract and storage placement under /engine/openai_compat/refs/state.json.

Change Type

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

Linked Issue

Closes #4443

Depends on #4442

Part of #3283

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 --features openai-compat-beta, cargo test -p ironclaw_reborn_openai_compat --test refs_contract, cargo test -p ironclaw_reborn_openai_compat_storage, cargo test -p ironclaw_architecture reborn_crate_dependency_boundaries_hold, cargo test -p ironclaw_architecture reborn_boundary_rules_active_crates_are_workspace_members
• cargo test --features integration if database-backed or integration behavior changed
• Manual testing: Not applicable; this is a contract/storage slice with no route behavior wired yet.
• 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
• cargo clippy -p ironclaw_reborn_openai_compat_storage --all-targets --all-features -- -D warnings
• git diff --check

Security Impact

Yes. This adds the OpenAI-compatible opaque ref/idempotency boundary used before route behavior is wired. Public refs do not encode tenant, user, thread, run, cursor, projection, or host paths. Ref lookup, stream resume, bind, and cancel semantics are actor/scope checked, and unauthorized refs are indistinguishable from nonexistent refs. Persisted mappings fail closed if corrupt or if the public id kind does not match the declared route surface.

Database Impact

No schema or migration changes. The durable adapter stores a CAS-protected JSON state record through RootFilesystem at /engine/openai_compat/refs/state.json; PostgreSQL/libSQL parity comes from the selected filesystem backend.

Blast Radius

Limited to the new Reborn OpenAI-compatible contract/storage crates, route DTO id typing, architecture boundary docs/tests, and Reborn storage-placement documentation. Existing v1 gateway behavior and concrete Reborn route handling are unchanged.

Rollback Plan

Revert this PR to remove the OpenAI-compatible ref/idempotency store and return the OpenAI-compatible contract surface to DTO/descriptors-only behavior from #4442.

Review Follow-Through

Reviewer judgment requested on whether the initial filesystem-backed single-state record is sufficient for the first route rollout slice, or whether indexed durable rows should be pulled forward before high-volume route behavior is wired.

---

Review track: C

[gemini-code-assist]

Code Review

This pull request introduces the ironclaw_reborn_openai_compat_storage crate and updates ironclaw_reborn_openai_compat to implement durable, filesystem-backed storage adapters for OpenAI-compatible public references and idempotency mappings. The changes establish the OpenAiCompatRefStore port and its implementations, along with boundary rules, documentation, and tests. Feedback from the review suggests replacing a hand-rolled hex encoding implementation with the standard hex crate and adding documentation to clarify that string length limits are validated in bytes to avoid character-counting overhead.

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.

[abbyshekit]

Code review — feat(reborn): add OpenAI-compatible product refs

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

Independent review of an open PR.

2 findings — 1 High, 1 Medium. Posted as a comment (advisory). Confidence ≥ 50, deduplicated across reviewers.

Sev	Conf	Reviewer	Location	Finding
High	85%	performance	lib.rs:225	All actors' ref mappings serialize through one global state.json CAS record — O(N)/op + write contention that fails under concurrency
Medium	65%	conventions	refs.rs:54	Newly-added validated newtypes use #[serde(transparent)], the pattern types.md explicitly flags

---

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

[think-in-universe]

Review pass for the #3283 OpenAI-compatible refs slice. I found two remaining fail-closed validation gaps in the durable storage path.