feat(api): consolidate versioned API and tagged release contracts

[seonghobae]

Objective

Replace five parallel API/release contract pull requests with one exact current-main foundation that keeps operation identity, runtime version negotiation, v1 compatibility, byte-exact OpenAPI provenance, and tagged release evidence on the same authority line.

This PR advances issue #315 and release hardening, but does not claim complete route/DTO/schema parity, generated clients, naruon consumer certification, release publication, signing, deployment, or GA completion.

Exact candidate

• protected base and merge base: main@06633a25109c62e24a7015ae04fb9f6e0a246f7e;
• exact head: 773230ea6da50dcfe1d9ac4d800c443024c78a62;
• branch: feat/versioned-api-release-contract-foundation-current-main;
• compare: four commits ahead, zero behind;
• changed paths: exactly 12 newly added workflow/Java/Python/test files;
• existing protected-main files changed or deleted: zero.

Preserved source authorities

The branch preserves the exact current-head source/test blobs from:

• fix(openapi): enforce stable unique operationIds #337 — stable unique OpenAPI operationId contract;
• feat(api): enforce explicit v1 negotiation contract #379 — explicit /api/v1/** runtime version negotiation;
• test(api): prevent silent v1 OpenAPI breaking changes #381 — immutable v1 operation/response compatibility baseline;
• test(api): bind OpenAPI provenance on current main #426 — exact OpenAPI byte provenance bound to source revision;
• test(release): require tagged acceptance on current main #427 — read-only tagged release acceptance workflow.

No stale ancestry, unrelated shared-file change, predecessor check result, or generated repair artifact was imported.

Integrated repairs

The former #426 and #427 contracts were disconnected: tagged release evidence did not generate or package the OpenAPI provenance record. This candidate repairs that gap.

The tag workflow now:

1. checks out and verifies the exact tag revision with read-only contents permission;
2. installs hash-locked Python test dependencies;
3. runs the repository's API and buyer-readiness script contracts;
4. binds tag name to the Maven project version;
5. runs authoritative Maven acceptance;
6. generates CycloneDX and buyer-release license evidence;
7. creates openapi-release-provenance.json from exact source SHA and exact OpenAPI bytes;
8. packages both raw OpenAPI and provenance JSON;
9. includes both in release-manifest.sha256 with the JAR, SBOM, license result, POM, source SHA, and tag;
10. uploads evidence only, without tag/release/publish/deploy authority or secrets.

test_api_release_contract_foundation.py additionally proves the same current OpenAPI bytes satisfy unique operation identity, the checked-in v1 compatibility baseline, and the release provenance digest.

Runtime/API invariants

• every shipped HTTP operation has one non-empty unique generated-client identity;
• an explicit unsupported or conflicting version fails before controller dispatch;
• missing/blank version header remains backward-compatible with path-selected v1;
• removing an approved operation, changing its operationId, or removing a documented response is breaking;
• additive operation/response changes remain compatible;
• release provenance hashes exact regular-file bytes and a canonical lowercase 40-hex source revision;
• symlinked, replaced-during-read, non-regular, or oversized OpenAPI authority fails closed.

Queue convergence

#337, #379, #381, #426, and #427 were closed as superseded by this exact current-main implementation owner after their source/test/workflow blobs were preserved. Their checks and reviews remain historical provenance and do not count for this candidate.

Scope boundary

Issue #315 remains open for complete controller/DTO/error/security parity, public schema completeness, generated SDKs, standalone+naruon consumer tests, deprecation/migration policy, event-contract versioning, and release publication/provenance signing.

Verification boundary

The branch was constructed from exact Git blobs because the execution environment could not resolve github.com for a local clone. No local Maven/Python result is claimed. Repository exact-head CI, Security Scan, SAST Semgrep, fuzz where emitted, workflow-contract tests, coverage, Javadocs, review threads, and qualifying independent approval are authoritative.

Merge gate

Keep Draft until every exact-head required check is terminal-success and all valid findings are resolved. Move to Ready only after the combined API/release contract and full repository acceptance pass. Merge or auto-merge only after a qualifying independent non-author approval covers the unchanged exact head and ordinary protection accepts it. Any head/base movement invalidates prior evidence.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f80e019a-1673-48b4-b15b-c7b16e7fcab9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}