feat(persistence): persist idempotent analysis runs

[seonghobae]

Summary

• add normalized tenant-scoped analysis_run_request and append-only analysis_run_state_event persistence
• atomically create accepted receipts, return stable opaque run IDs for exact retries, and reject divergent idempotency reuse
• enforce forward lifecycle transitions, FORCE RLS, immutable history, and tenant-bound model-artifact digest provenance
• document the partial issue [Product Completion] Deliver an executable end-to-end TEPP analysis run #166 boundary without claiming worker restart or full backup/restore acceptance

Exact current head

• Head: 17830159dbcb486fe05739c8153c9e495c91d076
• Base: main@b03cc378228d5e568fc34970fcb23dc2b452f535
• mergeable_state: blocked (ruleset 18156473 requires two independent approvals)
• No formal independent APPROVED reviews on current head. Bot COMMENTED only.
• Checks: most terminal success including Live PostgreSQL integration, Format/lint/test, Semgrep, OSV, Trivy, Scorecard; Production line coverage in_progress; opencode-review failure on prior run.

Verification

• cargo test -q --workspace
• cargo clippy -q --workspace --all-targets -- -D warnings
• cargo test -q -p persistence_postgres
• PostgreSQL 18.4 live integration: migration, identical/conflicting retry, accepted-to-terminal, duplicate terminal refusal, append-only refusal
• authored lines: 1198/1198 (100%)
• Rust docstring and canonical documentation validators

Refs #166

Do not self-approve. Do not --admin merge. Independent human approvals required. Checks are not blockers — keep shipping after two independent approvals on exact head.

[coderabbitai]

Warning

Review limit reached

Next included review available in 36 minutes.

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: Pro Plus

Run ID: 6a543678-e6ef-4377-afb9-d37e7cfdfb8b

📥 Commits

Reviewing files that changed from the base of the PR and between 61257fa and 12f9a22.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (18)

• CHANGELOG.md
• crates/analysis_engine/src/lib.rs
• crates/analysis_engine/src/topic_lineage_artifact.rs
• crates/analysis_engine/tests/topic_lineage_execution_contract.rs
• crates/persistence_postgres/Cargo.toml
• crates/persistence_postgres/src/analysis_run_sql.rs
• crates/persistence_postgres/src/lib.rs
• crates/persistence_postgres/src/live_pool.rs
• crates/persistence_postgres/src/sqlx_live.rs
• crates/persistence_postgres/tests/analysis_run_persistence_contract.rs
• crates/persistence_postgres/tests/live_postgres.rs
• docs/API_CONTRACT.md
• docs/ERD.md
• docs/OPERABILITY.md
• docs/TRACEABILITY.md
• docs/research/analysis-run-idempotent-persistence.md
• migrations/0008_analysis_run_persistence.down.sql
• migrations/0008_analysis_run_persistence.up.sql

📝 Walkthrough

Walkthrough

분석 실행 요청과 상태 이벤트를 PostgreSQL에 영속화하는 기능을 추가했습니다. 정규 요청 JSON과 SHA-256 digest를 저장하고, 테넌트별 멱등 삽입과 append-only 상태 전이를 적용합니다. Rust SQL 생성 API, 마이그레이션, 계약 테스트, 실제 PostgreSQL 테스트와 관련 문서를 추가했습니다.

Changes

분석 실행 영속화

Layer / File(s)	Summary
분석 실행 스키마와 마이그레이션 migrations/0008_analysis_run_persistence.*.sql, crates/persistence_postgres/src/migration.rs, docs/ERD.md	analysis_run_request와 analysis_run_state_event 테이블을 추가했습니다. 상태 전이, artifact digest, 테넌트 격리, FORCE RLS, append-only 변경 차단을 정의했습니다. 롤백 SQL과 ERD도 추가했습니다.
Rust SQL 계약과 공개 API crates/persistence_postgres/src/analysis_run_sql.rs, crates/persistence_postgres/src/error.rs, crates/persistence_postgres/src/lib.rs, crates/persistence_postgres/Cargo.toml	정규 요청 JSON, SHA-256 digest, 실행 ID와 상태 이벤트를 생성하고 검증하는 타입과 함수를 추가했습니다. 멱등 요청 삽입, 상태 이벤트 삽입, 최신 상태 조회 SQL을 공개했습니다.
계약 검증과 실행 테스트 crates/persistence_postgres/tests/analysis_run_persistence_contract.rs, crates/persistence_postgres/tests/live_postgres.rs	SQL 계약과 입력 검증을 테스트했습니다. 실제 PostgreSQL에서 멱등 재시도, 충돌 요청 거부, Failed 이벤트, 중복 이벤트 거부와 UPDATE 차단을 검증했습니다.
계약 및 설계 기록 docs/API_CONTRACT.md, docs/TRACEABILITY.md, docs/adr/0013-bitemporal-persistence-reproducibility-and-split-authority.md, docs/research/analysis-run-idempotent-persistence.md, CHANGELOG.md	API 계약, 요구사항 추적, ADR 성숙도, 설계 연구 문서와 변경 로그에 분석 실행 영속화 내용을 기록했습니다.

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

Merge Risk: 🟡 Moderate · up to 61257

This PR adds durable tenant-scoped analysis-run records and stable retries, but the current head still risks failed exact retries, production traffic blocking during migration, and weakened tenant isolation if callers do not bind tenant context correctly. Merge should wait until these issues are fixed or explicitly accepted; the remaining documentation mismatches are non-blocking.

Sequence Diagram(s)

sequenceDiagram
  participant Caller as 호출자
  participant RustAPI as insert_analysis_run_request_sql
  participant PostgreSQL
  Caller->>RustAPI: AnalysisRunRequestRecord 전달
  RustAPI->>RustAPI: 정규 JSON과 SHA-256 digest 검증
  RustAPI-->>Caller: INSERT SQL 반환
  Caller->>PostgreSQL: 멱등 요청 및 accepted 이벤트 삽입
  PostgreSQL-->>Caller: 저장된 실행 ID와 digest 검증 결과
  Caller->>RustAPI: 상태 이벤트 전달
  RustAPI-->>Caller: 상태 이벤트 INSERT SQL 반환
  Caller->>PostgreSQL: append-only 상태 이벤트 삽입
  PostgreSQL-->>Caller: 상태 전이 및 테넌트 제약 결과

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 6 files. (9 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 테넌트 범위의 멱등 분석 실행 영속화라는 PR의 주요 변경을 정확하고 간결하게 설명합니다.

Full details: Docstring Coverage

Explanation

Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 6 files. (9 skipped: 9 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/analysis-run-persistence

---

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

[devin-ai-integration]

Devin Review found 1 new potential issue.