PolicyEngine / PolicyEngine/chronicle

Assertion axis cannot represent provisional (revisable) observations

Open
#160 0 comments 0 reactions 0 assignees View on GitHub

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), keeping assertion two-valued, plus
  • possibly an assertion_policy vocabulary 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.