Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -273,7 +273,7 @@ stops startup instead of leaving a healthy-looking partial schema, and
application code must not compensate for a missing table.

Period leftover pairs (ADR 0017 / 0018 / 0048 / 0049 / 0119 / 0158 / 0162 /
0163 / 0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291) are computed in `lineageweave/leftover_pairs.py` from the
0163 / 0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292) are computed in `lineageweave/leftover_pairs.py` from the
residual after a real GRM/GPCM score, never invented. Distances are
Euclidean on the two-dimensional Gabriel leftover map; missing cells stay
out of the factorization. Closest and farthest post–criterion pairs
Expand Down Expand Up @@ -395,6 +395,7 @@ singular values `σ_k` so leftover-map axis share is not read as leftover-map
structure without the Gabriel scale that produced it; a missing, non-finite,
or negative singular value omits that `σ` badge independently of leftover-map
axis share and does not invent `σ_k` from leftover-map axis share.
ADR 0292 captions leftover-axis report badges with persisted leftover-map singular values `σ_k` when finite and non-negative, including rank-0 zero singular values; missing, non-finite, or negative singular values omit only the `σ` caption and never derive `σ_k` from leftover-map axis share.
ADR 0290 captions the grouping comparison strip with persisted leftover-map post complete-case coverage only when the caller can see the full persisted grouping population. Partial-visibility groupings omit that aggregate; never reconstruct the psychometric denominator from visible members, leftover pairs, or plotted markers.
ADR 0291 captions the grouping comparison strip with persisted leftover-map item complete-case coverage through leftoverMapItemCoverageCounts only when the caller can see the full persisted grouping population. Partial-visibility rows inherit ADR 0290's fail-closed coverage boundary and never recompute psychometric coverage from visible members, leftover pairs, or plotted criterion markers.
When `R`, `R̂`, `U`, `x`,
Expand Down
3 changes: 2 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,7 @@ information at the group's mean θ (Lord, 1980 max-info CAT). Rankings
persist to `report_item_information`. After those IRT main effects,
residual SVD leftover pairs on two Gabriel axes (Jeon et al., 2021;
ADR 0017 / 0048 / 0049 / 0119 / 0148 / 0158 / 0162 / 0163 / 0164 / 0168 /
0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291) persist to `report_leftover_pair` with signed residual `R`,
0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292) persist to `report_leftover_pair` with signed residual `R`,
observed `Y`, expected `E[Y|θ, item]`, full leftover-map rank, unexplained
leftover, ADR 0201 reconstruction evidence, ADR 0185 cross-share evidence,
ADR 0233 unexplained leftover share `s`, ADR 0266 explained leftover
Expand Down Expand Up @@ -671,6 +671,7 @@ incomplete item coverage. ADR 0288 fail-closes leftover-map post complete-case c
on the leftover pair list through leftoverMapCoverageCounts. ADR 0289 captions leftover-map
graphic axes with persisted leftover-map singular values `σ_k`. ADR 0290 captions the grouping comparison strip with persisted leftover-map post complete-case coverage under a full-visible-grouping rule; partial-visibility groupings fail closed that aggregate to avoid disclosing a hidden population denominator.
ADR 0291 captions grouping-comparison persisted item complete-case coverage through leftoverMapItemCoverageCounts only under ADR 0290's full-visible-grouping authorization boundary.
ADR 0292 captions leftover-axis report badges with persisted finite, non-negative leftover-map singular values `σ_k`; missing or invalid singular values omit only that caption, and axis share remains a distinct persisted measure.
Click a post marker or a pair button
opens that post. Those ADRs are the normative mathematical, storage, and
display contracts. Leftover-map axis share
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.d/2.49.0-leftover-map-axis-singular.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## 2.49.0 — Leftover-map singular values on leftover-axis badges

- Caption leftover-axis report badges with persisted leftover-map singular
values `σ_k` (ADR 0292). After `make seed`, leftover-axis badges name
persisted leftover-map singular values when finite together with persisted
leftover-map axis share, leftover-map graphic axes name those same singular
values, leftover-map axis ticks match `ξ (x, y) ζ (x, y)` on the pair row,
and leftover pairs sit above the member list; click a leftover pair opens
that post. A missing, non-finite, or negative singular value omits that
`σ` badge and keeps `leftover axis {k} {share}%`. Rank-0 unused axes still
name `σ 0.00`. Pair-list leftover-axis badges stay distinct from leftover-map
graphic axis captions. Do not invent `σ_k` from leftover-map axis share.
Never invent a leftover score. Never invent a theta. No new columns.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ All notable changes to this project are documented here. Format follows

### Added

- Period leftover pairs now caption leftover-axis report badges with persisted leftover-map singular values `σ_k` (ADR 0292 / v2.49.0). Missing, non-finite, or negative singular values omit only that `σ` caption; rank-0 zero remains `σ 0.00`, and axis share remains distinct.

- Grouping comparison rows now name persisted leftover-map item complete-case coverage (ADR 0291 / v2.48.0) only when the caller can see the full persisted grouping population; partial-visibility rows omit the aggregate rather than leaking a denominator or recomputing subset coverage.

- Grouping comparison rows now expose persisted leftover-map post complete-case coverage through `leftoverMapCoverageCounts` (ADR 0290 / v2.47.0) only for fully visible grouping populations. Partial-visibility rows omit the aggregate instead of leaking the full-group denominator or recomputing psychometric coverage from the visible subset.
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ cutoff. Global Ask optional `knowledge_cutoff` uses the same cover

Create/start endpoint rules (ADR 0017 / 0021), tie-vs-miss similarity
(ADR 0026), R&R catalog ids (ADR 0019 / 0027), leftover pairs
(ADR 0048–0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291), occupational construct catalog search
(ADR 0048–0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292), occupational construct catalog search
(ADR 0257), the text-channel embedding swap and cosine
clamp (ADR 0190), per-edge channel-score persistence (ADR 0195),
token-backed status notices (ADR 0220),
Expand Down
4 changes: 3 additions & 1 deletion docs/adr/0148-leftover-map-axis-share.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
**Amended by:** [ADR 0269](0269-leftover-map-axis-share-plot.md)
(leftover-map axis share on the graphic display);
[ADR 0289](0289-leftover-map-plot-singular.md)
(leftover-map singular values on the graphic display)
(leftover-map singular values on the graphic display);
[ADR 0292](0292-leftover-map-axis-singular.md)
(leftover-map singular values on leftover-axis badges)

## Context

Expand Down
163 changes: 163 additions & 0 deletions docs/adr/0292-leftover-map-axis-singular.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# ADR 0292 — Name leftover-map singular values on leftover-axis badges

**Decision status:** Proposed
**Date:** 2026-08-30

Amends leftover-map axis share persistence
([ADR 0148](0148-leftover-map-axis-share.md)). Independent of leftover-map
singular values on the graphic display
([ADR 0289](0289-leftover-map-plot-singular.md)), fail-close leftover-map post
complete-case coverage on the pair list
([ADR 0288](0288-leftover-map-list-post-coverage-helper.md)), leftover-map
incomplete item coverage on the pair list
([ADR 0287](0287-leftover-map-list-incomplete-item.md)), leftover-map incomplete
post coverage on the pair list
([ADR 0286](0286-leftover-map-list-incomplete-post.md)), leftover-map item
complete-case coverage on the pair list
([ADR 0285](0285-leftover-map-list-item-coverage.md)), leftover-map incomplete
item coverage on the graphic display
([ADR 0284](0284-leftover-map-plot-incomplete-item.md)), leftover-map incomplete
post coverage on the graphic display
([ADR 0283](0283-leftover-map-plot-incomplete.md)), leftover-map item
complete-case coverage on the graphic display
([ADR 0282](0282-leftover-map-plot-item-coverage.md)), leftover-map complete-case
coverage on the graphic display
([ADR 0281](0281-leftover-map-plot-coverage.md)), leftover-map rank on pair
segments ([ADR 0280](0280-leftover-map-segment-rank.md)), leftover expected on pair
segments ([ADR 0279](0279-leftover-map-segment-expected.md)), leftover observed on
pair segments ([ADR 0278](0278-leftover-map-segment-observed.md)), leftover
residual on pair segments ([ADR 0277](0277-leftover-map-segment-residual.md)),
leftover-map unexplained leftover on pair segments
([ADR 0276](0276-leftover-map-segment-unexplained-leftover.md)), leftover-map
cross share on pair segments ([ADR 0275](0275-leftover-map-segment-cross-share.md)),
leftover-map unexplained leftover share on pair segments
([ADR 0274](0274-leftover-map-segment-unexplained-share.md)), leftover-map
explained leftover share on pair segments
([ADR 0273](0273-leftover-map-segment-explained-share.md)), leftover-map
reconstruction on pair segments
([ADR 0272](0272-leftover-map-segment-reconstruction.md)), leftover-map
distance on pair segments ([ADR 0271](0271-leftover-map-segment-distance.md)),
leftover-map coordinate ticks ([ADR 0270](0270-leftover-map-coordinate-ticks.md)),
leftover-map axis share on the graphic display
([ADR 0269](0269-leftover-map-axis-share-plot.md)), leftover residual
disclosure ([ADR 0162](0162-leftover-residual-disclosure.md)), leftover
observed `Y` / expected `E` ([ADR 0163](0163-leftover-observed-expected.md)),
leftover-map explained leftover share persistence
([ADR 0266](0266-leftover-map-explained-share.md)), leftover-map
unexplained leftover share persistence
([ADR 0233](0233-leftover-map-unexplained-share.md)), leftover-map
reconstruction persistence ([ADR 0201](0201-leftover-map-reconstruction.md)),
leftover-map cross share persistence
([ADR 0185](0185-leftover-map-cross-share.md)), leftover-map unexplained leftover
persistence ([ADR 0182](0182-leftover-map-unexplained.md)), leftover-map rank
persistence ([ADR 0164](0164-leftover-map-rank.md)), leftover-map complete-case
coverage persistence ([ADR 0168](0168-leftover-map-complete-case-coverage.md)),
and leftover-map graphic display ([ADR 0268](0268-leftover-map-graphic-display.md)).


This successor identity is orthogonal to ADR 0290 (grouping comparison post coverage) and ADR 0291 (grouping comparison item coverage). Those authorization decisions remain unchanged; this UI decision does not reinterpret their persisted denominators.

## Context

ADR 0148 already persists leftover-map singular values `σ_k` and leftover-map
axis share `σ_k² / Σ_j σ_j²` and captions leftover-axis report badges with
share only. ADR 0289 already captions leftover-map graphic axes with persisted
`σ_k`. Those leftover-axis badges still hide `σ_k`, so Gabriel (1971)
singular values appear on the plot and never on the report-level leftover-axis
badges that name the same axes. Hiding `σ_k` on the badges lets leftover-map
axis share be read as leftover-map structure even when the buyer cannot tell
whether axis 1 is large because `σ_1` is large or because axis 2 collapsed.

This increment captions leftover-axis report badges with already persisted
leftover-map singular values. It does not add columns. It does not invent
`σ_k` from leftover-map axis share. It does not persist leftover-map inner
product, cosine, or length. It does not land Post quality on the leftover
criterion. Leftover-map distance stays two-axis Euclidean. Do not invent a
leftover score. Do not invent a theta.

The dashboard stack already used neighbouring leftover facts under other
numbers. This protected increment uses **0290** so it does not collide with
leftover-map singular values on the graphic display (0289), fail-close
leftover-map post complete-case coverage on the pair list (0288), leftover-map
incomplete item coverage on the pair list (0287), leftover-map incomplete post
coverage on the pair list (0286), leftover-map item complete-case coverage on
the pair list (0285), leftover-map incomplete item coverage on the graphic
display (0284), leftover-map incomplete post coverage on the graphic display
(0283), leftover-map item complete-case coverage on the graphic display (0282),
leftover-map complete-case coverage on the graphic display (0281), leftover-map
rank on pair segments (0280), leftover expected on pair segments (0279),
leftover observed on pair segments (0278), leftover residual on pair segments
(0277), leftover-map unexplained leftover on pair segments (0276), leftover-map
cross share on pair segments (0275), leftover-map unexplained leftover share on
pair segments (0274), leftover-map explained leftover share on pair segments
(0273), leftover-map reconstruction on pair segments (0272), leftover-map
distance on pair segments (0271), leftover-map coordinate ticks (0270),
leftover-map axis share on the graphic display (0269), leftover-map graphic
display (0268), leftover-map coordinates (0267 / migration 0245), leftover-map
explained leftover share persistence (0266 / migration 0244), leftover-map
unexplained leftover share persistence (0233 / migration 0233), leftover-map
reconstruction persistence (0201 / migration 0206), leftover-map cross share
(0185), leftover residual disclosure, leftover observed `Y` / expected `E`,
leftover-map rank, two-axis leftover-map distance, leftover coverage,
leftover-map axis share persistence (0148), leftover interaction-map
persistence, occupational construct catalog search (0265), or the dashboard
stacks.

## Decision

On leftover-axis report badges, caption leftover-map axis `k` with persisted
leftover-map singular value `σ_k` when that singular value is finite and
non-negative, including rank-0 zero singular values. Pair-list labels stay
distinct from graphic labels: leftover-axis badges stay
`leftover axis {k} σ {value} {share}%`; leftover-map graphic axes stay
`leftover-map axis {k} σ {value} ({share}%)`. A missing, non-finite, or
negative singular value omits that `σ` badge and keeps the existing
`leftover axis {k} {share}%` text. Do not invent `σ_k` from leftover-map axis
share. Axis 1 and axis 2 stay independently named. Click a leftover pair to
open that post. The grouping comparison strip (ADR 0149) stays on its reduced
leftover payload and does not gain this caption.

Do not add SQL. Do not edit shipped migrations. Do not persist inner
product, cosine, or length as separate columns. Do not invent a leftover
score. Do not invent a theta.

## Consequences

After `make seed`, leftover-axis report badges name persisted leftover-map
singular values when finite together with persisted leftover-map axis share;
click a leftover pair opens that post. Hidden posts stay hidden. Rank-0 unused
axes still name `σ 0.00`. Leftover-map graphic axes (ADR 0289) remain.

## Related

Independent of leftover interaction-map persistence, leftover-criterion
evaluation landing, leftover residual disclosure, leftover observed
`Y` / expected `E`, leftover-map complete-case coverage, leftover-map
axis share persistence, leftover pairs on the grouping comparison
strip, two-axis leftover-map distance, leftover-map rank, leftover-map
inner product, leftover-map cosine, leftover-map length, leftover-map
reconstruction, leftover-map unexplained leftover, leftover-map cross
share, leftover-map unexplained leftover share, leftover-map explained
leftover share, leftover-map coordinate persistence, leftover-map
graphic display, leftover-map coordinate ticks, leftover-map axis share
on the graphic display, leftover-map complete-case coverage on the graphic
display, leftover-map item complete-case coverage on the graphic display,
leftover-map incomplete post coverage on the graphic display, leftover-map
incomplete item coverage on the graphic display, leftover-map item
complete-case coverage on the pair list, leftover-map incomplete post
coverage on the pair list, leftover-map incomplete item coverage on the
pair list, fail-close leftover-map post complete-case coverage on the
pair list, and leftover-map singular values on the graphic display.

## References

Gabriel, K. R. (1971). The biplot graphic display of matrices with
application to principal component analysis. *Biometrika, 58*(3),
453–467. https://doi.org/10.1093/biomet/58.3.453

Jeon, M., Jin, I. H., Schweinberger, M., & Baugh, S. (2021). Mapping
unobserved item–respondent interactions: A latent space item response
model with interaction map. *Psychometrika, 86*(2), 378–403.
https://doi.org/10.1007/s11336-021-09762-5
(LSIRM interaction `−γ‖ξ_j − ζ_i‖` after main effects
`α_j − β_i`; typically `p = 2` for the interaction map.)
2 changes: 1 addition & 1 deletion frontend/package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "frontend",
"private": true,
"version": "2.48.0",
"version": "2.49.0",
"type": "module",
"scripts": {
"dev": "vite",
Expand Down
4 changes: 2 additions & 2 deletions frontend/src/App.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4143,8 +4143,8 @@ describe("App, authenticated", () => {
expect(screen.getByText(/TEST-PU-REPORT/)).toBeInTheDocument();
expect(screen.getAllByText("shared metric").length).toBeGreaterThan(0);
expect(screen.getAllByText(/CAT: sales-lead I=0\.70/).length).toBeGreaterThan(0);
expect(screen.getAllByText(/leftover axis 1 82%/).length).toBeGreaterThan(0);
expect(screen.getAllByText(/leftover axis 2 18%/).length).toBeGreaterThan(0);
expect(screen.getAllByText(/leftover axis 1 σ 1\.84 82%/).length).toBeGreaterThan(0);
expect(screen.getAllByText(/leftover axis 2 σ 0\.86 18%/).length).toBeGreaterThan(0);
expect(screen.getByLabelText("Leftover-map axis share")).toHaveTextContent(
"Open a leftover pair to read the post–criterion cell",
);
Expand Down
Loading