Repository navigation
docs: ADR-053, temporal distribution of imprecise UCDP events (#533) - #539
Open
Polichinel wants to merge 1 commit into
Open
Polichinel wants to merge 1 commit into
Polichinel wants to merge 1 commit into
Conversation
The temporal axis had a mechanism, a measured evaluation, a registered strategy and a named profile, and no governing decision. ADR-023 pins the parity invariants without deciding which strategy is correct; ADR-049 says in as many words that the temporal half "remains an open question and is not settled by this ADR". This closes that gap. Decides activity-weighted temporal distribution, triggered on UCDP's own date_prec >= 4 declaration rather than on ceil_split's magnitude proxy, through the conserving apportionment rounder. Two measurements drive it, both taken against builds from the same store: - date_end_only produces a calendar artifact. December carries 12.27% of all state-based fatalities ever recorded and October 13.33%, against 8.33% for an even year. Events with date_prec >= 4 are 26.7% of state-based mass and their date_end months are not uniform: 28.09% land in October, 26.09% in December. Of the December enders 85.8% start in January (Jan-Dec annual spans); of the October enders 88.8% start in August, dominated by one event (463137, 121,848 fatalities, Aug-Oct 2022). December is systematic, October is one event. - The spatial fix alone makes it worse. kgi_distributed moves December from 12.27% to 15.60% and widens the annual spread from 6.99pp to 9.38pp, because exclude_where_prec=() readmits 43,933 events carrying 785,626 fatalities that are overwhelmingly annual summary events, then stacks every one on its end month. Shipping ADR-049's recommendation without a temporal decision would have deepened the seasonality defect while closing the spatial one. Prior art is recorded rather than claimed as novelty: the legacy UCDP ingestor already spread summary events across their span, and ceil_split reproduces it exactly. This ADR changes the trigger (declared precision, not best >= span), the rounding (exact, not ceil, which reports 96 deaths across 74 events that appear in no source version), the weights (observed activity, not flat), and removes the annual date_end_only override that preempted the whole mechanism for every finalised release. Status is Proposed. It does not change what the pipeline invokes, does not settle source_distribution_map, and does not close C-37. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds ADR-053 — Temporal Distribution of Imprecise UCDP Events (Known Temporal Imprecision), the twin of ADR-049 on the other axis, and indexes it in
docs/ADRs/README.md.Status: Proposed. Documentation only — no source file is touched, and nothing about what the pipeline invokes changes.
Why
ADR-049 governs what to do when UCDP does not know where an event happened. Nothing governed what to do when it does not know when. The temporal axis had a mechanism (
temporal_distribution.py), a held-out evaluation (scripts/evaluate_temporal_allocation.py), registered strategies and a named profile (kgi_kti_activity) — and no decision record. ADR-023 pins the parity invariants without deciding which strategy is correct, and ADR-049 states explicitly that the temporal half "remains an open question and is not settled by this ADR."ADR-000 requires code and ADRs to agree. There was nothing to agree with.
The two measurements that drive it
Both taken against builds from the same consolidated store.
1.
date_end_onlyproduces a calendar artifact.Share of state-based fatalities by calendar month, whole store:
production_paritykgi_kti_activityAn even year is 8.33%. Events with
date_prec >= 4are 26.7% of state-based mass, and theirdate_endmonths are not uniform — 28.09% in October, 26.09% in December. Of the December enders 85.8% start in January (Jan–Dec annual spans). Of the October enders 88.8% start in August, dominated by a single event (463137, 121,848 fatalities, Aug–Oct 2022).So December is systematic and October is one event large enough to bend the whole-history distribution by itself. Both are endpoint-placement artifacts; only one is seasonal.
This matters more than the spatial artifact because models learn seasonality. A spatial spike is one wrong cell. A calendar spike is a recurring twelve-month signal present in every year of training data.
2. The spatial fix alone makes it worse.
kgi_distributed— ADR-049's recommendation, spatial axis only — moves December from 12.27% to 15.60% and widens the spread from 6.99 pp to 9.38 pp.exclude_where_prec=()readmits 43,933 events carrying 785,626 fatalities (+22.6%) that are overwhelmingly annual summary events, spreads them correctly across space, then stacks every one into the same month.Shipping ADR-049's recommendation without a temporal decision would have deepened the seasonality defect while closing the spatial one.
Prior art, recorded rather than claimed as novelty
The legacy UCDP ingestor already spread summary events across their span (
fix_summary_events), andceil_splitreproduces it hunk for hunk — confirmed in the dossier's legacy-loader forensics. This ADR does not introduce temporal distribution to VIEWS; it restores it, and fixes three defects plus the reason it stopped running:ceil_splitbest >= span— magnitude proxy,date_precnever consulteddate_prec >= 4and span > 1ceil(v/m)— does not conservedate_end_onlyoverride preempts itThe rounding defect is measured, not inferred:
ceil_splitreports 96 deaths across 74 events that appear in no version of the source store. Both apportioning strategies report zero.Why activity over uniform
Held out, each event removed from its own indicator, 20,000 events with known true month:
date_end_only(parity)uniform_spanactivity_weightedThe ADR states plainly that the gain is in the mean, not the median — median hit share is 0.00 for all three — so this helps the typical fatality, not the typical event.
It also argues that uniform's flatter year (2.33 pp) is a different distortion rather than a better one: it smears a year-long war into twelve identical months, erasing genuine seasonality along with the fake kind.
What the ADR deliberately does not hide
A new observer it proposes
§Validation adds a distributional guard: December's share of state-based fatalities must stay below 9.0%. No per-event assertion can see this defect. ADR-049's 2026-11-04 amendment records what happens without such a guard — cell 148759 grew from 273,076 to 274,358 and nothing went red, "a decision with no observer," concern C-365's mechanism.
What it does not decide
build_viewpoint.pystill defaults toproduction_parityandrefresh_pipeline.shstill passes it.source_distribution_map— named in §7 as under separate discussion with Håvard.Validation
ruff check .— cleantests/test_docs_citations.py,test_falsification_doc_consistency.py,test_falsification_docs_current.py,test_falsification_impl_doc_consistency.py,test_adr049_profile_contract.py— 44 passeddevelopment, exceptnotebooks/summary_event_allocation.ipynb, which is in docs: a notebook for summary-event allocation, and two findings it surfaced (#533) #538 and also targetsdevelopment.Correction made during drafting
An earlier draft attributed October's spike to Jan–Oct spans. Measured, that is wrong — 88.8% of October enders start in August, and the peak is essentially one event. Corrected before commit, and the measurement is in the ADR rather than the inference.
Related
development.🤖 Generated with Claude Code
https://claude.ai/code/session_01EfeuULbPTqrx4qtNki5dy9