Skip to content

chore: verify sanitized #830 reconstruction on exact #829 #978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
seonghobae wants to merge 4 commits into from
Closed

chore: verify sanitized #830 reconstruction on exact #829 #978

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ef5fcf6
feat(reports): leftover-map singular values on grouping comparison st…
seonghobae Aug 30, 2026
ed7beaf
chore(reports): sanitize historical #830 delta for current-parent rec…
seonghobae Sep 7, 2026
653330d
chore(reports): drop superseded historical ADR identity from #830 rec…
seonghobae Sep 7, 2026
70221cc
chore(reports): drop superseded historical release identity from #830…
seonghobae Sep 7, 2026
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
79 changes: 29 additions & 50 deletions AGENTS.md
View file
Open in desktop
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 / 0292) 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 / 0293) 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 All @@ -294,7 +294,12 @@ buttons; omit the plot when coordinates are missing; click a post
marker to open that post. ADR 0269 captions those leftover-map axes
with persisted leftover-map axis share `σ_k² / Σ_j σ_j²` when finite,
including rank-0 zero-share axes; a missing or non-finite share omits
that axis badge and keeps the existing leftover-map axis text. ADR 0270
that axis badge and keeps the existing leftover-map axis text. ADR 0289
captions those leftover-map axes with persisted leftover-map singular
values `σ_k` when finite and non-negative, including rank-0 zero
singular values; 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 0270
ticks leftover-map axes at the origin and at each unique finite
persisted `ξ` / `ζ` coordinate so the pair-row badge matches the
plot; rank-0 unused axes name only `0` and do not invent drawing-scale
Expand Down Expand Up @@ -385,45 +390,15 @@ non-integer payload cannot caption a contradictory `used N of M scored posts`
note; a missing, non-integer, negative-used, non-positive-scored, or
used-greater-than-scored coverage omits that leftover-map coverage note and
does not invent post coverage from plotted marker count.
ADR 0289 captions the grouping comparison strip with persisted leftover-map
post complete-case coverage through leftoverMapCoverageCounts so a buyer who
compares leftover pairs can read how many scored posts entered each grouping's
Gabriel factorization; a missing, non-integer, negative-used, non-positive-scored,
or used-greater-than-scored coverage omits that leftover-map comparison coverage
note and does not invent post coverage from leftover pair count or plotted
marker count. The strip does not gain leftover-map incomplete post coverage,
leftover-map incomplete item coverage, or the leftover-map graphic.
ADR 0290 captions the grouping comparison strip with persisted leftover-map
item complete-case coverage through leftoverMapItemCoverageCounts so a buyer who
compares leftover pairs can read how many scored criteria entered each grouping's
Gabriel factorization; a missing, non-integer, negative-used, non-positive-scored,
or used-greater-than-scored item coverage omits that leftover-map comparison item
coverage note and does not invent item coverage from leftover pair count or plotted
criterion marker count.
ADR 0291 captions the grouping comparison strip with persisted leftover-map
incomplete post coverage through leftoverMapIncompletePostCount so a buyer who
compares leftover pairs can read how many scored posts stayed out of each grouping's
Gabriel factorization; a missing, non-integer, or negative dropped count, or a
dropped count that contradicts usable complete-case integers, omits that leftover-map
comparison incomplete post note and does not invent dropped posts from scored minus
used or from leftover pair count. Dropped `0` is shown when persisted. The strip
does not gain leftover-map incomplete item coverage or the leftover-map graphic.
ADR 0292 captions the grouping comparison strip with persisted leftover-map
incomplete item coverage through leftoverMapIncompleteItemCount so a buyer who
compares leftover pairs can read how many scored criteria stayed out of each grouping's
Gabriel factorization; a missing, non-integer, or negative dropped count, or a
dropped count that contradicts usable item complete-case integers, omits that leftover-map
comparison incomplete item note and does not invent dropped criteria from scored minus
used or from leftover pair count. Dropped `0` is shown when persisted. The strip
does not gain the leftover-map graphic.
ADR 0293 captions the grouping comparison strip with persisted leftover-map
axis share through leftoverMapCompareAxisShare so a buyer who compares leftover
pairs can read Gabriel inertia of residual SVD axes 1 and 2 for that grouping;
a missing or non-finite share omits that leftover-map comparison axis share
badge and does not invent leftover-map axis share from leftover-map singular
value, leftover pair count, or plotted marker count. Share `0` is shown when
persisted, including rank-0 unused axes. The strip does not gain leftover-map
singular values or the leftover-map graphic.
ADR 0289 captions leftover-map graphic axes with persisted leftover-map
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.
ADR 0293 captions the grouping comparison strip with persisted leftover-map incomplete-post count only under the same full-visible-grouping authorization boundary. Partial-visibility groupings omit the aggregate and never derive dropped posts from the visible subset or scored-minus-used. Persisted valid dropped `0` remains visible.
When `R`, `R̂`, `U`, `x`,
`s`, and `e` are finite, `e + s + x = 1`. When `Y`, `E`, and `R` are
finite, `Y − E = R`. When `R`, `R̂`, and `U` are
Expand All @@ -434,18 +409,12 @@ list so a click opens that post with the leftover criterion current
in Post quality (ADR 0158). Leftover-map axis share (ADR 0148) is Gabriel inertia of
residual SVD axes 1 and 2 and persists to `report_leftover_map_axis`.
Rank-0 residuals emit two zero-share axes; the shares are report-level
and are not a leftover score. Complete-case coverage (ADR 0168) persists to
and are not a leftover score. Leftover-map singular values on the graphic
display (ADR 0289) name persisted `σ_k` on those leftover-map axes when
finite. Complete-case coverage (ADR 0168) persists to
`report_leftover_map_coverage` and captions the pair list and the leftover-map
graphic with how many scored posts entered the map. Pair-list post complete-case
coverage (ADR 0288) fail-closes that pair-list note through leftoverMapCoverageCounts.
Grouping comparison complete-case coverage (ADR 0289) captions the grouping
comparison strip with how many scored posts entered each grouping's map.
Grouping comparison item complete-case coverage (ADR 0290) captions the grouping
comparison strip with how many scored criteria entered each grouping's map.
Grouping comparison incomplete post coverage (ADR 0291) captions the grouping
comparison strip with how many scored posts stayed out of each grouping's map.
Grouping comparison incomplete item coverage (ADR 0292) captions the grouping
comparison strip with how many scored criteria stayed out of each grouping's map.
Item complete-case coverage
(ADR 0282) captions the leftover-map graphic with how many scored criteria
entered the map. Item complete-case coverage on the pair list (ADR 0285)
Expand Down Expand Up @@ -567,3 +536,13 @@ columns). Do not silently rewrite either historical form. The SHACL
shapes graph (`docs/ontology/lineageweave-kg-shapes.ttl`) is the
closed-world data-validation boundary for DB-to-RDF projections and is
published beside the ontology.

ADR 0294 keeps grouping-comparison incomplete-item coverage in the LineageWeave read-model boundary: consume only authorization-filtered persisted coverage for a full grouping, omit partial visibility, and never recompute psychometrics in the client.

ADR 0295 keeps grouping-comparison reconstruction in the LineageWeave read-model/UI boundary: format only persisted `R̂`, expose the value in the pair button accessible name, and never derive psychometric reconstruction from UI-visible proxies.

ADR 0296 adds persisted grouping-comparison explained-leftover share `e` in the LineageWeave read-model/UI boundary: expose it in the pair button accessible name, keep the duplicate visible badge presentation-only, and never derive or clamp psychometric values.

ADR 0367 exposes persisted grouping-comparison leftover-map axis share only for a fully caller-visible persisted grouping. Partial visibility returns no axis aggregate; never recompute it from visible members. Missing/non-finite share omits only the badge; persisted zero and finite negative values remain explicit.

ADR 0369 adds persisted grouping-comparison `U²/R²` only as a presentation/read-model consumer on exact #828. Never derive or clamp it, never recompute it from a visible subset, and include every finite buyer-visible comparison metric in the actionable pair button accessible name.
35 changes: 19 additions & 16 deletions ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -637,14 +637,15 @@ 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) 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 / 0293) 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
share `e`, and ADR 0267 leftover-map coordinates `ξ_{1:2}` / `ζ_{1:2}`.
ADR 0268 draws those persisted coordinates as the leftover-map graphic
display above the pair buttons. ADR 0269 captions leftover-map axes 1
and 2 with persisted leftover-map axis share. ADR 0270 ticks those
and 2 with persisted leftover-map axis share. ADR 0289 captions leftover-map
axes 1 and 2 with persisted leftover-map singular values `σ_k`. ADR 0270 ticks those
leftover-map axes at persisted `ξ` / `ζ` coordinates so the pair-row
badge matches the plot. ADR 0271 captions leftover-map pair segments
with persisted leftover-map distance `d`. ADR 0272 captions leftover-map
Expand All @@ -667,16 +668,11 @@ item coverage. ADR 0285 captions the leftover pair list with persisted leftover-
item complete-case coverage. ADR 0286 captions the leftover pair list with persisted leftover-map
incomplete post coverage. ADR 0287 captions the leftover pair list with persisted leftover-map
incomplete item coverage. ADR 0288 fail-closes leftover-map post complete-case coverage
on the leftover pair list through leftoverMapCoverageCounts. ADR 0289 captions the
grouping comparison strip with persisted leftover-map post complete-case coverage
through leftoverMapCoverageCounts. ADR 0290 captions the grouping comparison strip
with persisted leftover-map item complete-case coverage through leftoverMapItemCoverageCounts.
ADR 0291 captions the grouping comparison strip with persisted leftover-map incomplete
post coverage through leftoverMapIncompletePostCount.
ADR 0292 captions the grouping comparison strip with persisted leftover-map incomplete
item coverage through leftoverMapIncompleteItemCount.
ADR 0293 captions the grouping comparison strip with persisted leftover-map axis share
through leftoverMapCompareAxisShare.
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.
ADR 0293 captions grouping-comparison persisted incomplete-post count only for a fully caller-visible persisted grouping; partial visibility omits the aggregate rather than disclosing or recomputing a hidden-population count.
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 All @@ -694,10 +690,7 @@ including on the pair list. Results persist to
`GET /api/reports/{grouping}` lists the trend;
`GET /api/reports/{grouping}/{period}` is ABAC-filtered;
`GET /api/reports/compare/{period}` is the home-page grouping strip
and carries the same ABAC-filtered leftover pairs (ADR 0149) plus persisted
leftover-map complete-case coverage (ADR 0289), leftover-map item complete-case
coverage (ADR 0290), leftover-map incomplete post coverage (ADR 0291), and leftover-map
incomplete item coverage (ADR 0292);
and carries the same ABAC-filtered leftover pairs (ADR 0149) plus persisted leftover-map post complete-case coverage (ADR 0290) and item complete-case coverage (ADR 0291) only when the caller-visible member population equals the persisted grouping population;
`POST .../rebuild` scores every grouping kind (post_admin). `make seed`
folds A-100/B-200 Event Lineage fixtures (and the Riverbend calendar
post) that already have constructed IRT cells into the same shared
Expand Down Expand Up @@ -1096,3 +1089,13 @@ so it also covers the multi-entity opposite-order case a per-name lock
would still deadlock on. Every already-cataloged entity still resolves
through the unchanged, lock-free similarity-matching fast path; only
the rare creation branch serializes.

ADR 0294 adds persisted incomplete-item coverage to grouping comparison presentation while the API remains the full-group visibility authority; the frontend formats only an admitted persisted count.

ADR 0295 adds persisted `R̂` to grouping-comparison pair buttons. The explicit button accessible name carries the reconstruction label/value; the visible duplicate badge is presentation-only. Psychometric computation remains owned by fast-mlsirm.

ADR 0296 adds persisted explained-leftover share `e = R̂²/R²` to grouping-comparison pair actions; the button accessible name is authoritative for assistive technology and fast-mlsirm remains psychometric owner.

ADR 0367 adds persisted `leftover_map_axes` to the grouping-comparison read model under the same whole-population authorization rule as other psychometric aggregates. The UI consumes persisted `leftover_share` through `leftoverMapCompareAxisShare`; no subset recomputation or singular-value derivation is permitted.

ADR 0369 composes persisted finite grouping-comparison `leftover_map_unexplained_share` into pair actions. The parent button accessible name and visual badge share one formatter result; the visual duplicate is `aria-hidden`. Authorization and psychometric ownership remain upstream/current-parent contracts.
Loading