From b6f5e2ced65935fd4a675f8756265150bf6d2fb0 Mon Sep 17 00:00:00 2001 From: seonghobae Date: Tue, 25 Aug 2026 12:28:06 +0900 Subject: [PATCH 1/3] docs(leftover): align cross share with raw residual --- docs/adr/0003-fast-mlsirm-report-integration.md | 6 +++--- docs/adr/0048-persist-lsirm-leftover-pairs.md | 6 +++--- docs/adr/0049-leftover-pair-report-ui.md | 2 +- migrations/0185_report_leftover_map_cross_share.sql | 11 +++++------ 4 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/adr/0003-fast-mlsirm-report-integration.md b/docs/adr/0003-fast-mlsirm-report-integration.md index 455f3d90f..5b87cb5d5 100644 --- a/docs/adr/0003-fast-mlsirm-report-integration.md +++ b/docs/adr/0003-fast-mlsirm-report-integration.md @@ -104,12 +104,12 @@ than one large PR: 0182 / 0185): after IRT main effects, persist closest and farthest post–criterion pairs from the residual leftover map, and name unexplained leftover `U = R − R̂` and leftover-map cross share - `x = 2 R̂_c U_c / R̃²` of centered leftover when Gabriel coordinates + `x = 2 R̂ U / R²` of raw residual when Gabriel coordinates exist so the identity remainder after two-axis reconstruction is not read as leftover residual, leftover-map distance, explained leftover share, or unexplained leftover share. Do not persist leftover-map - explained leftover share `e`, unexplained leftover share `s`, or - two-axis reconstruction `R̂`. Do not fork LSIRM; do not invent a + explained leftover share `e`, unexplained leftover share `s`, or any other + unsupported share alias in this slice. Do not fork LSIRM; do not invent a leftover-pair API inside `fast-mlsirm` in this slice. 8. **Leftover-map axis-share slice** (ADR 0148): persist Gabriel inertia `σ_k² / Σ_j σ_j²` of leftover-map axes 1 and 2 on the same residual diff --git a/docs/adr/0048-persist-lsirm-leftover-pairs.md b/docs/adr/0048-persist-lsirm-leftover-pairs.md index d8957230a..b22769b84 100644 --- a/docs/adr/0048-persist-lsirm-leftover-pairs.md +++ b/docs/adr/0048-persist-lsirm-leftover-pairs.md @@ -43,12 +43,12 @@ leftover row also names unexplained leftover `U = R − R̂` when Gabriel coordinates exist so the leftover cell the two-axis map does not reconstruct is not read as leftover residual `R` or leftover-map distance `d` (ADR 0182), and names leftover-map cross share -`x = 2 R̂_c U_c / R̃²` of centered leftover when Gabriel coordinates +`x = 2 R̂ U / R²` of raw residual when Gabriel coordinates exist so the identity remainder after two-axis reconstruction is not read as leftover residual `R`, leftover-map distance `d`, explained leftover share `e`, or unexplained leftover share `s` (ADR 0185). -Two-axis reconstruction `R̂` / `R̂_c` and centered unexplained leftover -`U_c` are computed internally and are not persisted. +This ADR does not add a persisted reconstruction column; later ADR 0186 +governs that separate field. Cascade the rows with `report_period_score`. A leftover post must also be a `report_member_score` row, and the leftover criterion diff --git a/docs/adr/0049-leftover-pair-report-ui.md b/docs/adr/0049-leftover-pair-report-ui.md index 8a8477845..bad7b0063 100644 --- a/docs/adr/0049-leftover-pair-report-ui.md +++ b/docs/adr/0049-leftover-pair-report-ui.md @@ -32,7 +32,7 @@ explicitly names no leftover structure, and unexplained leftover names "leftover map leaves unexplained `U` after IRT main effects; open this post to read the named criterion" when present. When leftover-map cross share is also present, the next action instead names the identity -remainder `x` two leftover-map axes leave of centered leftover after +remainder `x` two leftover-map axes leave in raw residual after IRT main effects. A missing or non-finite value falls back in order — cross share, then unexplained leftover, then the existing closest/farthest next action. Clicking the button opens that post with diff --git a/migrations/0185_report_leftover_map_cross_share.sql b/migrations/0185_report_leftover_map_cross_share.sql index 7174c9d1a..e7d8957bf 100644 --- a/migrations/0185_report_leftover_map_cross_share.sql +++ b/migrations/0185_report_leftover_map_cross_share.sql @@ -1,14 +1,13 @@ --- ADR 0185: persist leftover-map cross share x = 2 R̂_c U_c / R̃² of --- the centered leftover after two-axis leftover-map reconstruction --- (R̃ = R − center, R̂_c = ξ_{1:2} · ζ_{1:2}, U_c = R̃ − R̂_c). --- Distance stays Euclidean leftover-map d. Centered leftover U_c and --- reconstruction R̂_c are computed internally and are not persisted. +-- ADR 0185: persist leftover-map cross share x = 2 R̂ U / R² of raw +-- residual after two-axis leftover-map reconstruction +-- (R̂ = ξ_{1:2} · ζ_{1:2}, U = R − R̂). Distance stays Euclidean +-- leftover-map d. This migration adds only the cross-share column. -- Upgrade column is nullable so older leftover rows keep distance and -- residual without fabricating a share. This migration is the single -- source of the column on fresh and existing installations. Do not -- edit shipped migrations 0001 / 0012 after the fact. Do not persist -- leftover_map_explained_share, leftover_map_unexplained_share, --- leftover_map_unexplained, or leftover_map_reconstruction. +-- leftover_map_explained_share or leftover_map_unexplained_share. -- Do not add a nonnegative CHECK: x may be negative when reconstruction -- and unexplained leftover have opposite signs. From be3314e4548da154f18afcbb63670e1f2eff8351 Mon Sep 17 00:00:00 2001 From: seonghobae Date: Tue, 25 Aug 2026 12:41:03 +0900 Subject: [PATCH 2/3] docs(leftover): remove dangling reconstruction ADR reference --- docs/adr/0048-persist-lsirm-leftover-pairs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/0048-persist-lsirm-leftover-pairs.md b/docs/adr/0048-persist-lsirm-leftover-pairs.md index b22769b84..7fdd2df72 100644 --- a/docs/adr/0048-persist-lsirm-leftover-pairs.md +++ b/docs/adr/0048-persist-lsirm-leftover-pairs.md @@ -47,8 +47,8 @@ distance `d` (ADR 0182), and names leftover-map cross share exist so the identity remainder after two-axis reconstruction is not read as leftover residual `R`, leftover-map distance `d`, explained leftover share `e`, or unexplained leftover share `s` (ADR 0185). -This ADR does not add a persisted reconstruction column; later ADR 0186 -governs that separate field. +This ADR does not add a persisted reconstruction column; persisting that +separate field requires its own accepted decision record. Cascade the rows with `report_period_score`. A leftover post must also be a `report_member_score` row, and the leftover criterion From 205b8a51a9fe55fd9b8de5ebe2b391f611f5a47b Mon Sep 17 00:00:00 2001 From: seonghobae Date: Tue, 25 Aug 2026 12:44:01 +0900 Subject: [PATCH 3/3] docs(migration): remove duplicate cross-share exclusions --- migrations/0185_report_leftover_map_cross_share.sql | 1 - 1 file changed, 1 deletion(-) diff --git a/migrations/0185_report_leftover_map_cross_share.sql b/migrations/0185_report_leftover_map_cross_share.sql index e7d8957bf..a1395f290 100644 --- a/migrations/0185_report_leftover_map_cross_share.sql +++ b/migrations/0185_report_leftover_map_cross_share.sql @@ -6,7 +6,6 @@ -- residual without fabricating a share. This migration is the single -- source of the column on fresh and existing installations. Do not -- edit shipped migrations 0001 / 0012 after the fact. Do not persist --- leftover_map_explained_share, leftover_map_unexplained_share, -- leftover_map_explained_share or leftover_map_unexplained_share. -- Do not add a nonnegative CHECK: x may be negative when reconstruction -- and unexplained leftover have opposite signs.