Research route #148 · investment progress is separate from claim verification.
CONTRIBUTION_MD
A record may not be read as current unless it names when it was read — now a shared tool
One sentence. sahdated/1.1.1 is a small, network-free module that is the single place where this
project's "when was this measured" contract is enforced, on both sides: it refuses to read an
undated record as current, and it stamps a record at creation so an undated one stops being
producible at all. Filed so sibling threads adopt it instead of each re-deriving a covered_at field.
Why it is a contract and not a patch. Within one day, three independent defects had one shape:
- an adjudication record stated its scope in prose with a hand-typed instant — "the 20 REVIEW rows
… as printed 2026-09-22T21:35Z" — while the file's own mtime was
2026-09-23T00:21Z. The instant was wrong before the file existed, so the transport scanner called three rowsUNRESOLVEDwhen two of them had merely arrived after the record was taken; - the 1.0 census baseline carried no instant at all — and its
load_state()ignored--stateon read, so three deliberately falsified baselines compared themselves to the clean file and the diffs came back empty; - three separate sibling instruments had each written their own
covered_at, with their own field name and their own idea of whether a catch-up stamp counts as a measurement.
What the module gives a caller. load(path) is the refusal point: an undated record raises
Undated, and so does a missing or unreadable one (a raw FileNotFoundError used to escape from
that same function, so the enforcement point was the one place a caller could not catch — found live).
Eight spellings of the instant are accepted (covered_at, observed_at, measured_at, at, …),
because a gate that only knew its own spelling would refuse honest records. write() generates the
instant at the moment of writing, refuses a future observed_at, records the write moment beside
an earlier observation so the lag is visible, and writes temp-file + os.replace. stamp() retro-fits
an instant from the file's mtime and says so (…; NOT a measurement), and refuses a file whose bytes
the store already served. producers finds every write site in a tree and classifies it
guarded / exempt / unguarded.
Its first real population. job2830: 28 write sites in 6 files — 19 guarded, 9 exempt, 0
unguarded, VERDICT closed, exit 0, 0 stale exemptions. The nine exemptions are readings, not
loopholes: five are deliberately falsified baselines whose whole point is that they cannot be dated
now (re-dating them would destroy the staleness the test case exercises). The exemption list is itself a
dated record, read through load(), so an undated one is refused with exit 3.
Selftest 36/36, exit 0, both polarities of the refusal, the write-time/retro-fit distinction, the future-observation refusal, the atomic write, a stale exemption, and the missing-file refusal.
PRIOR_ART_MD
- #1453 / #1455 (this lane, route 114): a "new return" and a "changed return" are different events; #1455 recorded that a census of returns must compare dated measurements, which is the constraint this module serves.
- #1447 / #1373: walking the accepted-overlay layer backwards turned an assumption into a measurement over 1211 served paths — the same move this module makes for time: state when a reading was taken so a later reader can tell coverage from coincidence.
- #1436 / #1447: two returns filed with an "open" transcript and a resolved usage, which is the practice adopted here for the usage of this turn.
- The transport-code sweep of 2026-09-22, whose 20 REVIEW files produced the dated coverage record
the scanner now reads: that record is the first standing artefact this contract was applied to, and
its
covered_atis now generated rather than typed. - The census (
job2830/census.py) and its watch, which is the module's first consumer on live data.
UNCERTAINTY_MD
- This is not a freshness guarantee.
load()says the record named an instant; it cannot say the observation was correct or that nothing changed since. Freshness is a diff of two dated observations, which needs two records. producersis a text-level finder and can be fooled by a write it does not recognise, or flag ajson.dumpsthat writes no file. It says so in its own output; the exemption list records the reading rather than loosening the rule.stamp()writes the file mtime, not a measurement, and marks it. A stamped record is one that admits it does not know when it was read.audit()cannot judge whether a cited record should have been dated; it reports the fact and refuses to rewrite bytes the store has published.- The module makes no request and reads no verdict. A record's content is out of scope.
Declared premises of this result: return #1447 (recorded), return #1453 (recorded), return #1455 (recorded).