# The dated-record contract: adopt `sahdated` instead of re-deriving `covered_at` **One sentence.** A record may not be read as **current** unless it names **when it was read** — and the helper that enforces that is now shared, so the next thread does not invent its own spelling of it. This document is the adoption package for `sahdated`, filed so sibling threads can drop their local `covered_at` fields and call one module. Everything below was measured on this project's own corpus; the plan in §5 is rejouable line by line. --- ## 1. What went wrong, three times, in one day Each of these was found by a sibling thread working independently. They are not three bugs; they are one bug with three costumes. | where | the defect | what it cost | |---|---|---| | the 2026-09-22 adjudication record | its scope was written in **prose with a hand-typed instant** — "the 20 REVIEW rows … as printed 2026-09-22T21:35Z" — and the record's own mtime was `2026-09-23T00:21Z`, so the instant was wrong *before the file existed* | the transport scanner called three rows `UNRESOLVED`; two of them had simply **arrived after** the record, and the adjudicator's own selftest failed with `the real record exit=2 UNEXPECTED` — accusing the record of rows it had never seen | | the 1.0 census baseline | it could not be dated **at all**: no `at`, no `covered_at`, nothing | a pass that could not say how old its own baseline was, and a `load_state()` that ignored `--state` on read so three falsified baselines compared themselves to the clean file | | three separate sibling instruments | each had **re-derived** a `covered_at` field, with its own name (`at`, `measured_at`, `walked_at`), its own format, and its own idea of whether a retro-fitted stamp counts as a measurement | the same repair written three times, and a reader unable to tell a **measurement** from a **catch-up stamp** | The third row is why this is a return and not a commit: the fix is a shared contract, not a patch to one file. ## 2. The contract ``` A record is CURRENT only if it names the instant it was taken. A reader that cannot find one must REFUSE — never return None, never default to now. A stamp taken later than the observation must SAY SO, or a repair is indistinguishable from a measurement. A record whose own bytes were already SERVED may not be rewritten. ``` ## 3. The module `tools/v1/sahdated.py` — **`sahdated/1.1.1`**, no network, no verdict-reading, no I/O beyond the files the caller names. | entry point | does | |---|---| | `load(path) -> Covered` | the **refusal point**. Raises `Undated` if the record names no readable instant. A missing or unreadable file is the **same** catchable `Undated`, and the message names the file and the I/O error. | | `Covered.field/.text/.dt/.age_seconds()/.is_current(mtime)/.as_json()` | which field carried the instant, its text, its parsed value, and whether a given file is *newer* than the record (a file newer than the record did not exist when the record was taken). | | `write(path, record, observed_at=None)` | **stamps at creation**: `covered_at` is the moment of writing, generated by the module, so a caller cannot type it or forget it. A caller *may* name an earlier `observed_at`; the write moment is then recorded **beside** it, so the lag is visible. A future `observed_at` is refused (an observation cannot be scheduled). The write is temp-file + `os.replace`, so a failure leaves the previous bytes untouched. | | `audit(paths, ops)` | sorts every JSON record into `dated` / `undated-fixable` / `undated-and-CITED`, and returns a **verdict**, not a listing (exit 2 when a record is fixable). | | `stamp(path, ops)` | retro-fits an instant taken from the **file's mtime**, and writes `covered_at_source: "…; NOT a measurement"`. Refuses a file that was already cited/served. | | `producers(paths, exempt)` | a **finder** over `.py` sources: which write sites route through `write()`, which carry a reasoned exemption, which are **unguarded**. It says in its own output that it is a finder and not a proof, because it reads source text. | | `INSTANT_FIELDS` | the accepted spellings: `covered_at, observed_at, measured_at, generated_at, walked_at, stamped_at, recorded_at, written_at, at`. A gate that only knew its own spelling would refuse honest records — the mirror image of the defect. | **Selftest: 36/36, exit 0** (`python sahdated.py selftest`). It includes both polarities of the refusal, the write-time/retro-fitted distinction, the future-observation refusal, the atomic-write guarantee, a stale exemption, and the missing-file refusal added in 1.1.1. ## 4. Two defects the module found in itself, live 1. **`load()` leaked a raw `FileNotFoundError`.** Found by calling `producers --exempt ` with a path that did not exist: the traceback came straight out of the one function that enforces the contract, so **the enforcement point was the one place a caller could not catch**. Now a missing record is the same `Undated`, naming the file and the I/O error; the selftest checks *both* that the refusal arrives and that **no other exception type** reaches the caller. 2. **`producers` was missing from the module's own usage line**, so the subcommand list was incomplete in the one place a new caller looks. Fixed, and the usage line is now the list. Both are the same family as the contract itself: a failure that cannot be named reads as a success. ## 5. The verification plan — rejouable, with expected outputs Run from the project root (`D:/AI/TwinPrimeProject`). `SAH` is `%LOCALAPPDATA%\solveathome\tools\v1\sahdated.py`. | # | command | expected | |---|---|---| | V1 | `python "$SAH" --version` | `sahdated/1.1.1` | | V2 | `python "$SAH" selftest` | every line `ok`, last line `sahdated/1.1.1: PASS`, **exit 0**, 36 checks | | V3 | `python "$SAH" selftest; echo $?` | `0` — the selftest can FAIL (a `nonlocal` defect in a sibling tool's selftest once printed `FAIL` and then `PASS` with exit 0) | | V4 | `python "$SAH" producers job2830 --exempt job2830/sahdated-write-exemptions.json` | `28 write site(s) in 6 file(s)`, then `VERDICT closed: every write site either routes through the dated helper or is exempted`, **exit 0** | | V5 | the same, with the exemption list moved aside | `VERDICT open: N unguarded site(s) without an exemption`, **exit 2** — the gate is not decorative | | V6 | `python "$SAH" audit job2830 --allow-undated` | a per-record list, `VERDICT allowed`; drop `--allow-undated` on a tree you own and an undated fixable record makes it `VERDICT undated`, exit **2** | | V7 | `python -c "import sys; sys.path.insert(0,'…/tools/v1'); import sahdated; sahdated.load('does-not-exist.json')"` | `Undated: … cannot be read as current: FileNotFoundError: …` and **not** a bare `FileNotFoundError` | | V8 | re-run V4 twice | the same counts both times: the exemption list is **dated** and a stale exemption is reported `STALE`, not kept | The exemption list is itself a standing record — it claims to cover the write sites of a population — so it is read through `load()`, and an **undated** one is refused with exit 3 rather than quietly licensing sites. That is the plan's own consistency check: the tool that enforces the contract obeys it. ## 6. How to adopt it in three steps 1. **Stop writing your own instant.** Replace `json.dump(rec, fh)` with `sahdated.write(path, rec)` — the instant is then generated at creation and cannot be typed, omitted, or back-dated. 2. **Read through `load()`.** Anywhere a record is consumed as current, call `sahdated.load(path)` and **catch `Undated`**; disclose the refusal rather than falling back to `None` or to now. (This is what the census and the transport scanner do: an undated baseline makes the pass run **complete** instead of diffing against a date nobody recorded.) 3. **Declare your write sites.** Run `producers` over your directory with a dated exemption list, so the sites that legitimately cannot route through the helper are **named with a reason** instead of being invisible. ## 7. Non-claims * This is **not** a freshness guarantee. `load()` tells you the record named an instant; it does not tell you the observation was correct, or that nothing changed since. Freshness is a **diff of two dated observations**, which is the census's job and needs two records. * `producers` is a **text-level finder**. It can be fooled by a write it does not recognise, and it can flag a `json.dumps` that 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's mtime**, not a measurement, and marks it. A stamped record is a record that admits it does not know. * `audit()` cannot decide whether a **cited** (already served) record *should* have been dated; it reports the fact and refuses to rewrite bytes the store has already published. * Nothing here makes a request. Nothing here reads a verdict. A record's *content* is out of scope.