feat: name leftover-map reconstruction on leftover pairs (v2.12.31)

[seonghobae]

Persist leftover-map reconstruction R̂ = ξ_{1:2} · ζ_{1:2} on period leftover pairs so landed unexplained leftover U = R − R̂ stays auditable as U + R̂ = R (ADR 0183).

Why this is not #564

#564 persists a centered leftover-map reconstruction that recovers R̃ (ADR 0186 / v2.12.30). Landed ADR 0182 already defines U = R − R̂ against the uncentered residual R = Y − E and the same two-axis inner product used for distance. Substituting centered R̃ would break U + R̂ = R.

This PR keeps that internal R̂ and names it on the pair row. Do not mix with leftover stacks #485, #521, #537, #539, #563, #564, or #579. Coverage #518 already landed as ADR 0168.

Buyer-visible change

After make seed, closest and farthest leftover pairs sit above the member list with signed R̂ next to leftover-map distance d; click opens that post. Missing or non-finite reconstruction omits the badge rather than inventing a leftover score. Signed reconstruction is stored, never clamped.

Contract

• Independent exact-head APPROVE required. Author will not self-approve.
• Squash-merge only with independent APPROVE + exact-head required success.
• Do not wait on Checks to keep implementing the next buyer gap.
• Issues Milestone 2: port verified direct-PostgreSQL analysis into the protected product architecture #79 and Milestone 2.1: add normalized runtime-analysis schema bridge after v0.77 #87 stay open. feat(ai): delegate product defaults to adaptive orchestration #96 stays closed.

---

Summary by CodeRabbit

• 새로운 기능

  • 잔여 쌍에 2축 재구성값 R̂을 저장하고 API와 보고서 화면에 표시합니다.
  • 재구성값이 있는 경우 해당 값과 잔차 거리, 설명되지 않은 잔여를 함께 확인할 수 있습니다.
  • 잔여 쌍을 선택하면 관련 게시물을 열 수 있습니다.
  • 재구성값과 설명되지 않은 잔여의 합이 전체 잔차와 일치하는지 감사할 수 있습니다.

• 개선 사항

  • 재구성값이 없거나 유효하지 않은 경우 기존 안내를 유지합니다.
  • 영어, 한국어, 중국어, 일본어, 베트남어 안내 문구를 지원합니다.

[coderabbitai]

Warning

Review limit reached

Next included review available in 30 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: 1c8eab9b-c7d9-44f3-a404-2c466dd777e9

📥 Commits

Reviewing files that changed from the base of the PR and between e4234bc and c33e777.

📒 Files selected for processing (21)

• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.d/2.12.31-leftover-map-reconstruction.md
• backend/app/report_ingestion.py
• backend/tests/test_api.py
• docs/adr/0003-fast-mlsirm-report-integration.md
• docs/adr/0048-persist-lsirm-leftover-pairs.md
• docs/adr/0049-leftover-pair-report-ui.md
• docs/adr/0201-leftover-map-reconstruction.md
• frontend/src/App.test.tsx
• frontend/src/api.ts
• frontend/src/components/LeftoverPairList.tsx
• frontend/src/i18n.test.ts
• frontend/src/i18n.ts
• lineageweave/leftover_pairs.py
• migrations/0206_report_leftover_map_reconstruction.sql
• migrations/rollback/0206_report_leftover_map_reconstruction.sql
• scripts/seed_demo_data.py
• tests/test_leftover_pairs.py
• tests/test_period_report.py
• tests/test_schema.py

📝 Walkthrough

Walkthrough

기간 보고서 leftover pair가 두 축 재구성값 R̂을 저장하고 API와 UI에 노출합니다. 유한한 값은 표시하며, 누락되거나 비유한 값은 기존 U 동작을 사용합니다. U + R̂ = R 검증과 스키마 마이그레이션이 추가되었습니다.

Changes

Leftover map reconstruction

Layer / File(s)	Summary
스키마와 재구성 계약 docs/adr/*, ARCHITECTURE.md, AGENTS.md, CLAUDE.md, migrations/*, CHANGELOG*	ADR 0201과 nullable leftover_map_reconstruction 컬럼을 추가했습니다. 재구성값 처리 규칙과 U + R̂ = R 관계를 문서화했습니다.
Pair 재구성 계산 lineageweave/leftover_pairs.py, tests/test_leftover_pairs.py	두 축 Gabriel 재구성값을 계산하고 유한한 값만 LeftoverPair에 저장합니다. 테스트는 재구성값과 잔차 합계를 검증합니다.
보고서 저장과 API 노출 backend/app/report_ingestion.py, scripts/seed_demo_data.py, backend/tests/test_api.py, tests/test_period_report.py	기간 보고서 저장 및 조회 경로에 새 필드를 연결했습니다. API 검증은 U + R̂ = R을 확인합니다.
Leftover pair UI 표시 frontend/src/api.ts, frontend/src/leftoverMapReconstruction.ts, frontend/src/components/*, frontend/src/i18n*, frontend/src/App.test.tsx	유한한 R̂을 부호 형식으로 표시하고 reconstruction 안내를 우선합니다. 값이 없으면 기존 unexplained 안내를 표시합니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🔵 Low · up to e4234

The change adds and displays leftover-map reconstruction values, while rollback requires the application to be downgraded before removing the new database column to avoid report-fetch failures. The PR is mergeable with explicit owner awareness and documented rollback sequencing.

Sequence Diagram(s)

sequenceDiagram
  participant ReportIngestion
  participant ReportLeftoverPair
  participant API
  participant LeftoverPairList
  ReportIngestion->>ReportLeftoverPair: store leftover_map_reconstruction
  API->>ReportLeftoverPair: read reconstruction
  ReportLeftoverPair-->>API: return nullable reconstruction
  API-->>LeftoverPairList: provide leftover pair data
  LeftoverPairList->>LeftoverPairList: format and display R̂

Loading

🚥 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	제목은 leftover pair에 leftover-map reconstruction을 명명하고 추가하는 주요 변경을 정확히 요약합니다. 구체적이고 간결하며 변경 내용과 직접 관련됩니다.
Docstring Coverage	✅ Passed	Docstring coverage is 86.67% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 16 files. (12 skipped: …
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 86.67% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 30 functions across 16 files. (12 skipped: 12 unsupported.)

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch feat/leftover-map-reconstruction-v21231

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/leftover-map-reconstruction-v21231

---

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]

Requesting independent Copilot review. Author will not self-approve. Exact-head APPROVE required before squash-merge.

[seonghobae]

Exact head e4234bce reconciles ADR 0182 context with its accepted ADR 0201 amendment: reconstruction was discarded at initial acceptance and is now retained so U + R̂ = R is auditable. Documentation hygiene: 5 passed; diff check passed. The five implementation-consistency notes are informational and resolved. Latest main still conflicts across the later leftover-map ladder, so no merge-ready or approval claim is made; the next loop must compose those accepted semantics without dropping protected-main work.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

📝 Info: Comparison strip does not use the reconstruction next-action

fetch_period_comparison adds leftover_map_reconstruction to the payload, but the comparison strip renders its own inline buttons (App.tsx) rather than LeftoverPairList, so the reconstruction next-action ordering never applies there. No messaging inconsistency results.

---

Was this helpful? React with 👍 or 👎 to provide feedback.