feat: persist leftover interaction-map coordinates (v2.12.19)

[seonghobae]

Period reports now persist complete-case leftover interaction-map coordinates ξ / ζ after IRT main effects and render a 2D Jeon / Gabriel map above leftover pairs (ADR 0121 / 0126). Click a post node or a leftover-pair criterion node to open that post.

This restacks the unique 2D-map increment from #481 onto current main@b4911f8 as v2.12.19. Closest/farthest leftover pairs already live on main. Do not mix into #74/#92. #96 stays closed.

Buyer next action

After seed, the leftover interaction map sits above leftover pairs. Click a post node or a highlighted leftover-pair criterion to open that post.

Constraints

• Rank-0 and rank-1 maps pad unused axes with zero. Do not invent a second component.
• Hidden posts stay hidden (same ABAC gate as leftover pairs).
• Never invent a leftover score or a theta.
• Synthetic fixtures only.
• Migration 0172_report_leftover_interaction_map.sql is four-digit replayed (ADR 0166).

Tests

• leftover + SQL contract + migration replay: 39 passed
• frontend LeftoverInteractionMap + i18n + App: 131 passed

Independent review required. Never self-approve. Squash-merge only with independent APPROVE + exact-head required success. Do not wait on Checks.

---

Summary by CodeRabbit

• 새로운 기능

  • 기간 보고서에 leftover interaction map을 추가했습니다.
  • 사람·기준 항목의 좌표와 가까운/먼 잔여 관계를 시각화합니다.
  • 지도에서 게시물 또는 기준 항목을 클릭하거나 키보드로 선택해 관련 게시물을 열 수 있습니다.
  • 낮은 차수의 지도는 사용하지 않는 축을 0으로 표시합니다.

• 개선 사항

  • 숨겨진 게시물과 불완전한 데이터는 지도에서 제외합니다.
  • 잔여 관계의 교차 공유 및 재구성 정보를 보고서에 표시합니다.
  • 관련 다국어 번역과 접근성 안내를 추가했습니다.
  • 지도 데이터와 보고서 결과의 표시 및 저장 안정성을 강화했습니다.

[coderabbitai]

Warning

Review limit reached

Next included review available in 17 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: 6c64822e-4af0-46da-968a-edae7de67d44

📥 Commits

Reviewing files that changed from the base of the PR and between d6e9929 and 689a21b.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (22)

• ARCHITECTURE.md
• CHANGELOG.md
• backend/app/main.py
• backend/tests/test_api.py
• docs/adr/0003-fast-mlsirm-report-integration.md
• docs/adr/0121-persist-leftover-interaction-map.md
• docs/adr/0208-externalize-local-mathematical-compute.md
• docs/adr/0211-fast-mlsirm-residual-interaction-map.md
• docs/doctoring/python-mathematical-compute-boundary-audit.md
• docs/storybook-inventory.md
• frontend/src/App.css
• frontend/src/App.test.tsx
• frontend/src/App.tsx
• frontend/src/api.ts
• frontend/src/i18n.test.ts
• frontend/src/i18n.ts
• lineageweave/leftover_pairs.py
• lineageweave/period_report.py
• pyproject.toml
• scripts/seed_demo_data.py
• tests/test_leftover_pairs.py
• tests/test_schema.py

📝 Walkthrough

Walkthrough

Changes

기간 보고서에 fast-mlsirm 기반 leftover interaction map의 person/item 좌표를 추가했습니다. 좌표와 leftover pair를 데이터베이스에 저장하고 API로 반환합니다. 보고서 UI는 SVG 맵과 post 탐색을 제공합니다. 관련 테스트, 번역, 문서, 마이그레이션을 갱신했습니다.

잔여 상호작용 맵

Layer / File(s)	Summary
맵 계산과 보고서 연결 lineageweave/leftover_pairs.py, lineageweave/period_report.py, tests/test_leftover_pairs.py, tests/test_period_report.py, pyproject.toml	잔여 맵 계산을 fast_mlsirm.residual_interaction_map에 위임합니다. 반환된 좌표, 축, coverage, pair 값을 제품 식별자에 매핑합니다. 범주 확률도 upstream 계약을 사용하고 반환 shape를 검증합니다.
맵 저장과 보고서 API migrations/0172_report_leftover_interaction_map.sql, migrations/rollback/0172_report_leftover_interaction_map.sql, backend/app/report_ingestion.py, backend/app/main.py, frontend/src/api.ts, scripts/seed_demo_data.py, backend/tests/test_api.py, tests/test_schema.py	person 및 item 좌표 테이블을 추가합니다. 보고서 저장·조회·비교·시드 흐름에 좌표를 연결합니다. API는 접근 제어와 데모 데이터 필터를 적용해 person 좌표를 반환합니다.
맵 렌더링과 탐색 frontend/src/LeftoverInteractionMap.tsx, frontend/src/App.tsx, frontend/src/App.css, frontend/src/LeftoverInteractionMap.test.tsx, frontend/src/LeftoverInteractionMap.stories.tsx, frontend/src/App.test.tsx, frontend/src/i18n.ts, frontend/src/i18n.test.ts, docs/adr/0121-persist-leftover-interaction-map.md, docs/adr/0126-leftover-map-criterion-node.md	기간 보고서에 SVG 맵을 표시합니다. closest와 farthest 관계를 구분합니다. 연결된 person과 criterion 노드는 클릭 또는 키보드 입력으로 관련 post를 엽니다. 좌표가 없으면 맵을 표시하지 않고 관련 메타데이터는 유지합니다.

아키텍처와 마이그레이션 검증

Layer / File(s)	Summary
아키텍처와 제품 계약 문서 ARCHITECTURE.md, docs/adr/0003-fast-mlsirm-report-integration.md, docs/adr/0049-leftover-pair-report-ui.md, docs/adr/0121-persist-leftover-interaction-map.md, docs/adr/0126-leftover-map-criterion-node.md, docs/adr/0207-fast-mlsirm-residual-interaction-map.md, docs/product-technical-gap-baseline.md, CHANGELOG.md, CHANGELOG.d/2.12.19-leftover-interaction-map.md, docs/storybook-inventory.md	fast-mlsirm과 LineageWeave의 책임 경계, leftover map 저장·표시·탐색 규칙, lineage API와 조직 별칭 규칙을 문서화합니다.
마이그레이션 재생과 스키마 검증 tests/test_migration_replay.py, tests/test_schema.py, tests/test_static_sql_review_contracts.py	마이그레이션 파일 형식, UTC 백필, FK 검증 분리, 기존 볼륨 재생, 재실행 안전성 및 SQL 검토 계약을 검증합니다.

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

Merge Risk: 🟠 High · up to d6e99

The PR adds persisted leftover interaction-map coordinates and a clickable map, but the current head can expose private posts across process-unit boundaries and can return 500 for private leftover-pair comparisons; invalid numeric values may also be persisted instead of marked unavailable. These concrete availability, authorization, and data-integrity risks should be fixed or explicitly accepted before merging.

Sequence Diagram(s)

sequenceDiagram
  participant ReportView
  participant ReportsAPI
  participant report_ingestion
  participant ReportMapTables
  ReportView->>ReportsAPI: 기간 보고서 요청
  ReportsAPI->>report_ingestion: 보고서 조회
  report_ingestion->>ReportMapTables: 맵 좌표와 pair 조회
  ReportMapTables-->>report_ingestion: person/item 좌표 반환
  report_ingestion-->>ReportsAPI: 맵 데이터가 포함된 보고서 반환
  ReportsAPI-->>ReportView: leftover interaction map 렌더링

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 complete-case leftover interaction-map 좌표를 영속화하는 PR의 주요 변경 사항을 명확하게 요약합니다. 좌표 시각화와 상호작용 변경까지 모두 포함하지는 않지만, 제목이 모든 세부 사항을 포함할 필요는 없습니다.
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 73.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 20 files. (9 skipped: 9 unsupported.)

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch feat/persist-leftover-interaction-map-v21219

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/persist-leftover-interaction-map-v21219

---

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 review on exact head 8640199. Closest/farthest leftover pairs already live on main; this increment only persists leftover-map ξ/ζ and renders the 2D map. Hidden posts stay hidden. Never invent leftover score/theta. Never self-approve. Squash-merge only with independent APPROVE + exact-head required success. Do not wait on Checks.

[seonghobae]

Cycle 2026-08-25T04:01 KST: leftover interaction-map coordinates remain independent of leftover-share/reconstruction stacks. Independent exact-head APPROVE required. This identity will not self-approve. Squash-merge only with independent APPROVE + exact-head required success.

[seonghobae]

Cycle comment: leftover-map coordinates (#579) still waits for independent APPROVE + exact-head required success. Do not self-approve. Recutting leftover-map length onto protected main as independent v2.12.31 / ADR 0187 (0183–0186 remain claimed by open leftover PRs). Never mix reconstruction/share/cosine/inner-product/coordinates into that recut.

[seonghobae]

Cycle comment: leftover increment still waits for independent APPROVE + exact-head required success. Author must not self-approve. Do not squash-merge without that APPROVE. Recut leftover-map length onto protected main as independent v2.12.31 / ADR 0187 (0183–0186 claimed by open leftover share/reconstruction PRs). Do not mix leftover stacks. Issues #79 and #87 stay open.

[seonghobae]

Remaining closed per ADR 0208 Decision 1 and owner direction (methodology rejected: no accepted paper basis for the residual-SVD/Gabriel leftover map; Python implementation rejected on performance). The construct belongs to fast-mlsirm's residual-interaction-map contract under ADR 0208's stacked delivery order. This PR will not merge; further reopenings should move the work to ContextualWisdomLab/fast-mlsirm instead.

[seonghobae]

ADR 0208 ownership verification at exact head f079ff1c: LineageWeave calls the pinned fast-mlsirm commit 369158bb through residual_interaction_map(..., axis_count=2). That Rust-backed owner contract exclusively returns complete-case admission, residuals, Gabriel coordinates, singular values/axis shares, distances, reconstruction, unexplained residual, and cross-share. lineageweave/leftover_pairs.py contains no SVD, factorization, coordinate, distance, reconstruction, cross-share, or residual-generation implementation; it performs only fail-closed envelope shape/finiteness/R = Y - E consistency validation, identifier mapping, deterministic closest/farthest selection, and persistence-facing projection. A malformed non-padded rank-one owner envelope now returns unavailable before indexing. Focused synthetic validation: 24 passed. This satisfies the owner-library boundary; it does not revive the removed Python numerical model.

[seonghobae]

Exact-head review reconciliation (2026-08-26):

• feat: persist leftover interaction-map coordinates (v2.12.19) #579 689a21b6: the process-unit scoped period-report finding is already present in this exact head: report_ingestion.py selects and serializes p.process_unit_id, and read_period_reports uses it for ABAC before stripping it. The empty-map path in leftover_pairs.py returns axes=() (with regression coverage in tests/test_leftover_pairs.py::test_empty_upstream_map_does_not_invent_product_evidence), so zero-share axes are not persisted for an invalid complete-case map.
• fix(semantic): preserve graph fact source provenance #632 3851c7cf: _graph_facts_for_posts performs one bounded query with a 64-fact global cap; gather_chat_sources calls it once per path and reuses the returned mapping. The cited duplicate-query review points to an older commit and is not present at this exact head.
• feat: publish calibrated external lineage contract #636 1230a1a7: AGENTS.md already states that active_weights fails closed on an active-channel mismatch and loads a separately calibrated exact-channel vector; it no longer mandates renormalization. ARCHITECTURE.md and ADR 0172 carry the same contract.
• feat(dashboard): quantify cases and preserve project journeys #640 4677052c: operations_dashboard.py currently computes primary_project_name by confidence desc, project_name, then uses it before the alphabetical project_names array. The cited fallback is not present at this exact head.

These are exact-head validations; no stale review snapshot was transferred as merge evidence. Hosted Checks and independent approval remain authoritative.