fix(release): prepare immutable wheel publication for retry-stacking repair

[seonghobae]

Scope

Prepare the canonical owner release path for Issue #1083. This PR is stacked on #1209 so its release changes can be reviewed separately from that PR's CI and runtime repairs.

• Build and verify the installable 0.2.0 Python wheel from the exact release commit, require two byte-identical builds at that commit's fixed timestamp, record its SHA-256 digest, and carry both into the existing immutable GitHub Release publication flow.
• Check the uploaded wheel and manifest bytes and verify release asset attestations before treating publication as successful.
• Build the locked Rust decision measurement before the release job's fresh full test suite, matching the existing Security workflow's prerequisite; use an isolated uv build and install check.
• Update the changelog, release runbook, and executable workflow contracts.

Local verification

• uv sync --python 3.12 --locked --extra api --extra db --extra queue --group dev --group native-build
• uv run --no-sync maturin develop --locked --release --features pyo3/extension-module --manifest-path rust/decision_receipt/Cargo.toml
• Release workflow and psychometric lock scope tests: 64 passed.
• actionlint .github/workflows/release.yml passed.
• Exact candidate HEAD fc68f66b: full suite 5,073 passed, 5 skipped, exit code 0.
• Two wheels built after the native test prerequisite matched byte-for-byte (SHA-256 f51d846c960d4004c5bc8ebd4be171889c7fe948752292cdd2342adfea155ef4). The wheel remained pure Python, installed in an isolated Python 3.12 target, and reported package version 0.2.0.
• Hosted checks and independent review remain required.

Merge and release boundary

#1209 must first reach protected main. Retarget this PR to main afterward and require its own current-head hosted checks and independent review before merge. Merging this PR prepares release machinery; it does not itself publish a tag or close #1083. A separate maintainer dispatch on protected main remains necessary for the immutable release and downstream consumer migration.

Refs #1083.

429 successor before publication

Noema's orchestrator/free JSON-schema flow exposed a separate all-429 final-synthesis gap. PR #1251 carries its bounded recovery, with source-side full-suite validation. This release workflow PR can prepare publishing independently, but the Issue #1083 artifact must be built from a protected descendant containing #1251, with fresh exact-head release checks and a new consumer review verdict. The fc68f66b local wheel is a reproducibility check of this PR's earlier head, not the final published artifact.

Current-head follow-up — 2026-09-26

At 5c4db18b2a7f0427fbbd3ab0ce19b733ab7e2574, the release verifier limits its SBOM lookup to successful security.yml push runs on main for the exact source commit. A scheduled run on the same SHA can no longer take the place of the certified push run. The scheduled-run-first execution regression passes; the release test set reports 146 passed (process exit 0), actionlint .github/workflows/release.yml passes, and git diff --check is clean.

Two builds from separate clean git archive trees at that exact SHA and fixed SOURCE_DATE_EPOCH were byte-identical to each other and to a worktree build: contextual_orchestrator-0.2.0-py3-none-any.whl, SHA-256 be80e38e1b7d89db850e3ec0a6505c62d9e31bdb0939b441d6b6fc7bd2404100. An isolated Python 3.12 install identified one contextual-orchestrator==0.2.0 distribution. This is local candidate evidence, not a published artifact or a first-release version decision. ADR 0137 in draft #1257 still lists the no-tag first-version choice as unresolved.

Hosted Security and Quality run 36237432504 completed successfully on this exact head: Tests and package quality, Property and coverage-guided fuzzing, Rust workspace gate, and CodeQL, supply chain, and SBOM all report SUCCESS. This establishes this PR head's Security result, not release readiness. There is still no independent PR review. Protected review, #1209 integration, the required release gate repair #1259, the package/licence path #1225/#1226, the required PyPI path #1258, full-scope SBOM evidence, and downstream released-contract checks remain separate release conditions. Do not dispatch publication from this PR head.

Summary by CodeRabbit

• 새로운 기능
  • 구조화된 응답 합성에서 모든 후보가 일시적으로 요청 제한(429)에 걸리면, 정해진 대기 시간 내에 복구를 기다린 뒤 재시도합니다. 요청 크기 제한으로 일부 후보가 제외된 경우에도 다른 후보를 계속 사용할 수 있습니다.
  • 릴리스에 검증된 Python 패키지와 체크섬 파일이 포함됩니다. 동일한 소스 커밋에서 만든 패키지의 일치 여부와 게시 자산의 서명을 확인합니다.
• 개선 사항
  • 릴리스 노트가 게시 길이 제한을 초과하면 줄 단위로 조정하고 전체 변경 로그 링크를 제공합니다.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

Next included review available in 21 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 0d6b49c0-deec-4c03-9174-cdf5b3ef1eed

📥 Commits

Reviewing files that changed from the base of the PR and between 5c4db18 and 45b29f7.

📒 Files selected for processing (8)

• .github/workflows/release.yml
• CHANGELOG.md
• docs/RELEASING.md
• scripts/ci/release_notes.py
• tests/test_release_immutable_publication.py
• tests/test_release_notes.py
• tests/test_release_supply_chain_contract.py
• tests/test_release_workflow_contract.py

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 527f9afd-71ae-4bf2-b70f-22dfcf338487

📥 Commits

Reviewing files that changed from the base of the PR and between 77d274f and 5c4db18.

📒 Files selected for processing (11)

• .github/workflows/release.yml
• CHANGELOG.md
• contextual_orchestrator/orchestrator.py
• docs/RELEASING.md
• docs/doctoring/autonomous_kpi_runbook.md
• scripts/ci/release_notes.py
• tests/test_release_immutable_publication.py
• tests/test_release_notes.py
• tests/test_release_supply_chain_contract.py
• tests/test_release_workflow_contract.py
• tests/test_structured_output_distinct_fallback.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

구조화 합성의 429 응답 처리와 후보 재시도 동작을 변경했습니다. 릴리스 workflow는 재현 가능한 Python wheel을 빌드하고, wheel 및 SHA-256 manifest를 릴리스 자산으로 검증·게시합니다. 릴리스 노트에는 GitHub 본문 길이 제한 처리를 추가했습니다.

Changes

구조화 합성 429 복구

Layer / File(s)	Summary
429 후보 처리 및 합성 재시도 contextual_orchestrator/orchestrator.py	429 응답을 일반 실패 기록과 요청 제외 처리에서 분리합니다. 후보가 모두 냉각 중이면 제한된 대기 예산 안에서 복구를 기다립니다. 조건을 충족하는 경우에만 재시도하고, 복구 실패나 기한 초과 시 route evidence를 포함한 오류를 반환합니다.
복구 동작 검증 및 기록 tests/test_structured_output_distinct_fallback.py, CHANGELOG.md, docs/doctoring/autonomous_kpi_runbook.md	429 재시도, cooldown, 예산 만료, 혼합 오류, schema repair 및 nonretryable 429를 검증합니다. CHANGELOG와 runbook에는 관련 동작과 검증 범위를 기록합니다.

검증된 wheel 릴리스

Layer / File(s)	Summary
릴리스 검증 및 wheel 빌드 .github/workflows/release.yml, docs/RELEASING.md, scripts/ci/release_notes.py, tests/test_release_notes.py, tests/test_release_supply_chain_contract.py, tests/test_release_workflow_contract.py	테스트 전에 잠금 의존성을 준비하고 release 모드 네이티브 확장을 빌드합니다. 대상 커밋의 시각을 사용해 Python wheel을 두 번 빌드하고 비교하며, 설치된 배포판의 메타데이터를 검증합니다. 릴리스 노트는 125,000자를 넘으면 줄 경계에서 자르고 전체 CHANGELOG 링크를 추가합니다.
publisher 입력 및 릴리스 자산 검증 .github/workflows/release.yml, docs/RELEASING.md, CHANGELOG.md, tests/test_release_immutable_publication.py	publisher 입력과 릴리스 상태 검사에 wheel과 SHA256SUMS를 추가합니다. Draft 자산을 업로드하거나 내려받아 입력 파일과 비교하며, 불완전한 불변 릴리스와 바이트가 다른 기존 wheel을 거부하는 테스트를 추가합니다.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to 5c4db

No identified issue blocks merging this preparation change. Publication remains a separate step with its stated prerequisites.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to 5c4db

The changes add useful checks before publication and bound provider retries. Two conditional risks remain: callers of one server can affect one another through shared cooldown state, and a release can become public before its final asset verification finishes. Neither is established as an active exploit.

Retained concerns

• Medium · security · inferred: An authenticated caller that induces provider 429 responses can affect later structured-synthesis requests sharing the server's agent pool. The new retry path skips or waits for agents using instance-wide, agent-keyed cooldown state rather than caller identity. The effect is bounded and does not expand the eligible provider pool.
• Medium · reliability · inferred: The draft becomes public before final release and wheel-asset verification. If an asset changes before publication or verification fails afterward, the job fails but cannot restore the draft; consumers could encounter a public wheel that has not passed the workflow's final acceptance gate. This is an extension of an existing non-atomic release transition, not a newly established unauthorized publishing path.

Security review details

Security Blast Radius

• inferred — Cooldown interference is bounded to requests sharing an orchestrator instance and agent pool; the evidence does not establish separate tenant credentials or a fleet-wide shared cooldown.

Security Findings and Attack Paths

• inferred — An authenticated caller able to produce upstream quota responses can cause other requests on the same instance to skip or wait for a shared agent. This is availability interference, not evidence of credential access or routing to an unauthorized provider.

Trust Boundaries and Controls

• observed — Typed nonretryable 429 and mixed-failure rounds remain terminal; virtual synthesis retries retain eligible-candidate filtering and a finite wait budget. Release publication checks existing asset bytes rather than overwriting mismatches.

Resilience and Maintainability Implications

• inferred — Final attestation detects a failed publication condition but occurs after the public-state mutation. The runbook requires verification before accepting a release, limiting downstream reliance when that procedure is followed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 재현 가능한 wheel 게시 준비와 retry-stacking repair를 정확히 설명합니다. 변경사항의 주요 목적과 관련되며 간결하고 구체적입니다.
Linked Issues check	✅ Passed	#1083의 코딩 요구사항을 구현했습니다. .github/workflows/release.yml은 동일 커밋과 고정 시각으로 두 wheel을 빌드하고 바이트와 SHA-256 manifest를 비교합니다. 설치된 배포판의 이름·버전·파일을 검증하고 wheel, manifest, SBOM, 서명 자산을 확인합니다. orchestrator.py와 회귀 테…
Out of Scope Changes check	✅ Passed	변경 범위는 #1083과 연결됩니다. retry/failover 동작과 회귀 테스트, immutable wheel publication workflow, manifest·SBOM·asset 검증, release notes, 릴리스 문서와 runbook, workflow contract tests만 변경했습니다. 요약에 독립적인 unrelated 변경은 없고…
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 35 functions across 6 files. (5 skipped: 4 …

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.