PolicyEngine / PolicyEngine/chronicle
Assertion axis cannot represent provisional (revisable) observations
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- Avg merge
- 11h 48m
- Merged PRs (30d)
- 45
Description
Context
#154 gave facts an assertion axis (observation vs source_projection) and target profiles an assertion_policy (observed_only / prefer_observed / allow_source_projection). The axis distinguishes measured-past from projected-future. It has no way to say a third thing: the publisher has marked this figure provisional and will revise it.
The case that surfaced it
ons-pipr-private-rent-march-2026 (#159): the February 2026 average private rents are provisional PIPR estimates — the bulletin says so explicitly — subject to routine revision in later editions. On the current axis they are correctly observations: they measure an elapsed period. But once ONS revises, the bundle carries a stale value indistinguishable from a final one, and a consumer resolving "latest" against a revisable figure is exactly the silent-wrong-answer case the assertion axis was built to prevent.
This will not be a one-package need: PIPR revises monthly, DWP Stat-Xplore series revise, ONS MYE revises back-years (the mid-2025 estimates publication also revises mid-23/24), and OBR restates. First-print packages are systematically exposed.
Design space (not deciding here)
- A third assertion state (
provisional_observation), or - an orthogonal per-fact flag (e.g.
revision_status: provisional | revised | final), keepingassertiontwo-valued, plus - possibly an
assertion_policyvocabulary extension for consumers that want to fence on it (e.g. warn or fail when a resolved fact is provisional).
An orthogonal flag avoids overloading the observed/projected boundary (a provisional estimate of an elapsed period is still an observation) and keeps #154's policy semantics intact, but the consumer-side story (_choose_period, series keying, warnings) needs thinking through either way.
Provenance
Filed from review discussion on #159, same shape as #157 (structural gap identified in a wave review, fixed outside the wave PR).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the assertion model and policy introduced in #154, then review the provisional case in #159 and the related gap in #157. Trace the consumer paths named in the issue, including _choose_period, series keying, and warnings. Done means the project has a decided representation for provisional observations and documented consumer policy semantics.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100