#!/usr/bin/env python3 """sahdated.py -- a record may not be read as CURRENT unless it names WHEN it was read. WHY THIS EXISTS (2026-09-23, job 2830) Two records in one run made the same mistake in two costumes, and both were found by a self-test rather than by reading: * the transport-adjudication record declared its extent in prose -- "the 20 REVIEW rows ... as printed 2026-09-22T21:35Z" -- with a HAND-TYPED instant that was already stale when the file was written. Three rows that existed at write time had never been enumerated; the scanner, having nothing to date them against, called them UNRESOLVED beside a genuinely unfinished row, and the adjudicator blamed its own record for rows it had never seen. * the census baseline had a machine instant from the start and a flag (`--state`) that was honoured for writing and silently ignored for reading, so a pass compared against a baseline nobody named. The defect is one layer above the wire and one layer above the data: a file that is TREATED AS CURRENT while saying nothing about when it was taken. So the remedy is a gate at that layer: rec = sahdated.load(path) # raises Undated if the record names no usable instant rec.dt, rec.field, rec.text, rec.is_current(mtime), rec.age_seconds() sahdated.write(path, record) # the write side: stamps at creation, atomically sahdated.stamp(path) # the repair side: mtime + a mark saying it is a retro-fit Refusing is the point. `load()` raises; there is no silent `None`. A caller that genuinely cannot date its record must catch `Undated` and SAY SO in its verdict -- which is what the transport scanner does -- rather than assume the record is fresh. THE WRITE SIDE (added 2026-09-23, second pass; 1.1.0). A gate that only refuses on READ leaves every generator free to keep producing undated records -- and the audit of this run's own output found 3340 of them. So `write(path, record)` writes a record that ALREADY names its instant, generated at the moment of writing, and the instant cannot be supplied by the caller. A caller whose observation genuinely happened earlier may pass `observed_at`; then `covered_at` is the observation and `written_at` is the write, so the lag between them is visible rather than smoothed away, and a FUTURE `observed_at` is refused (an observation cannot be scheduled). A retro-fit is marked as such in `covered_at_source` and `is_retro_stamped()` tells the two apart -- otherwise a repaired record would be indistinguishable from a measured one. TWO MORE PIECES, both from the same rule 1. `cited()` -- is this file already named in the run's own serve ops? A record whose bytes were served is CITED: rewriting it to add an instant would make the published copy disagree with the local one, which is the same class of lie one level up (the rule the adjudicator uses). 2. `stamp()` -- add an instant to a record that lacks one, deriving it from the file's own mtime and RECORDING THAT PROVENANCE (`covered_at_source`), and refusing outright if the file is cited. A retro-fitted instant may not masquerade as a measurement. AND THE PERIMETER (1.1.0). A helper only a willing caller uses is advice, not a contract, so this module also answers the two questions a reader of a record set actually has: * `audit()` now returns a VERDICT, not only a listing: an undated-and-fixable record makes the audit exit 2. It used to print such records and exit 0, so nothing downstream could fail on them -- a finding that cannot fail anything is the same shape of defect as a zero with no control. * `producers()` -- which files in this run WRITE a JSON record, and which of them can only do so through the dated helper. A production site that neither routes through `write()` nor names an instant is reported UNGUARDED unless it carries a reasoned exemption. It is a FINDER, not a proof: it reads source text, so it can be fooled, and it says so in its own output. This module never makes a request and never inspects a verdict: it reads files the caller names and tells it whether they are allowed to speak as current. CLI: python sahdated.py selftest python sahdated.py audit [ ...] [--ops ] python sahdated.py stamp [--ops ] python sahdated.py producers ... [--exempt ] python sahdated.py --version """ from __future__ import print_function import datetime import glob import hashlib import io import json import os import re import sys import tempfile # 1.1.1: two defects found live, in the module whose whole subject is a record that cannot be read # as current. (a) `load()` on a path that did not exist raised FileNotFoundError straight out of the # one function that enforces the contract, so the enforcement point was the one place a caller could # not catch -- hit by `producers --exempt ` with a mistyped path. A missing or unreadable record # is now the SAME catchable `Undated`, and it names the file and the I/O error. (b) `producers` was # missing from the module's own usage line, so the subcommand list was incomplete in the one place a # new caller looks. VERSION = "sahdated/1.1.1" # The field names that count as naming an instant. Deliberately a LIST and not one name: this # project already writes `at`, `covered_at` and `observed_at`, and a gate that only knows its own # spelling would refuse honest records -- the mirror image of the defect it repairs. INSTANT_FIELDS = ("covered_at", "observed_at", "measured_at", "generated_at", "walked_at", "stamped_at", "recorded_at", "written_at", "at") # A stamp that was RETRO-FITTED says so in this phrase; a record stamped at write time does not. # The distinction is what stops a repaired record from being indistinguishable from a measured one. RETRO_MARK = "NOT a measurement" # A record that carries this key is saying "this instant was retro-fitted", so a reader can tell a # measurement from a stamp instead of having to trust the field name. PROVENANCE_FIELD = "covered_at_source" class Undated(Exception): """Raised when a record would be read as current without naming when it was read.""" class Cited(Exception): """Raised when a record cannot be rewritten because the run already served its bytes.""" def parse_instant(text): """A UTC datetime, or None. Accepts the two shapes this project writes, and ISO-8601 with an offset, because a gate that refuses a well-formed instant teaches callers to fake one.""" if not isinstance(text, str): return None s = text.strip() if s.endswith("Z"): s = s[:-1] + "+00:00" try: dt = datetime.datetime.fromisoformat(s) except ValueError: return None if dt.tzinfo is None: dt = dt.replace(tzinfo=datetime.timezone.utc) return dt.astimezone(datetime.timezone.utc) def instant_of(record): """(field, text, datetime) for the first instant field the record carries, else (None,)*3.""" if not isinstance(record, dict): return None, None, None for f in INSTANT_FIELDS: dt = parse_instant(record.get(f)) if dt is not None: return f, record[f], dt return None, None, None def stamp_of(now=None): dt = now or datetime.datetime.now(datetime.timezone.utc) return dt.strftime("%Y-%m-%dT%H:%M:%SZ") def is_retro_stamped(record): """True only for a record whose instant was fitted after the fact.""" return isinstance(record, dict) and RETRO_MARK in str(record.get(PROVENANCE_FIELD) or "") def write(path, record, observed_at=None, source=None, now=None): """Write a record that ALREADY names its instant -- and cannot be talked out of it. This is the WRITE side of the contract. `load()` refuses an undated record; this makes one unproducible by a cooperating generator. The instant is generated HERE, at the moment of writing, because the defect it closes is a caller who typed one (the 1.0.0 adjudication record said "as printed 2026-09-22T21:35Z" and was already stale when the file landed) or omitted it (the census baseline). A caller whose observation genuinely happened earlier may pass `observed_at`; then BOTH instants are recorded -- `covered_at` is the observation, `written_at` is the write -- so the lag between them is visible to a reader instead of being smoothed away. A FUTURE instant is refused outright: that is not an observation, it is a claim about the future. Atomic, per this project's rule: temp file in the same directory, fsync, `os.replace`. A failure mid-write leaves the previous bytes untouched, which is tested. """ rec = dict(record) now_dt = now or datetime.datetime.now(datetime.timezone.utc) if observed_at is not None: obs = parse_instant(observed_at) or parse_instant(str(observed_at)) if obs is None: raise Undated("observed_at=%r is not a usable instant" % (observed_at,)) if obs > now_dt + datetime.timedelta(seconds=5): raise Undated("observed_at=%s is in the FUTURE (now %s): an observation cannot be " "scheduled" % (stamp_of(obs), stamp_of(now_dt))) rec["covered_at"] = stamp_of(obs) rec[PROVENANCE_FIELD] = source or ("observed by the caller, written at %s" % stamp_of(now_dt)) else: rec["covered_at"] = stamp_of(now_dt) rec[PROVENANCE_FIELD] = source or "measured at write time by %s" % VERSION rec["written_at"] = stamp_of(now_dt) text = json.dumps(rec, indent=1, sort_keys=True) + "\n" d = os.path.dirname(os.path.abspath(path)) or "." if not os.path.isdir(d): os.makedirs(d) fd, tmp = tempfile.mkstemp(dir=d, prefix=".sahdated-", suffix=".tmp") try: with io.open(fd, "w", encoding="utf-8", newline="\n") as fh: fh.write(text) fh.flush() os.fsync(fh.fileno()) os.replace(tmp, path) except BaseException: try: os.unlink(tmp) except OSError: pass raise return path class Covered(object): """A record that names its instant, plus the arithmetic that depends on it.""" def __init__(self, path, record=None): self.path = path if record is None: try: record = json.load(io.open(path, encoding="utf-8")) except (OSError, ValueError) as exc: # A MISSING or unreadable record is the same kind of fact as an undated one: it cannot # be read as current, and the caller must not get a traceback it would have to interpret. # Found live -- `producers --exempt ` on a path that did not exist raised # FileNotFoundError straight out of `load`, so the one place the contract is enforced # was the one place a caller could not catch it. raise Undated("%s cannot be read as current: %s: %s" % (path, type(exc).__name__, exc)) self.record = record self.field, self.text, self.dt = instant_of(self.record) if self.dt is None: # "no instant at all" and "an instant I cannot read" are different defects with different # remedies (add a stamp vs fix a bad value), so the refusal names which one it saw. The # distinction is real and was found by this selftest's own mutation: a record with # `at: "yesterday-ish"` was being reported as having NO instant field. broken = [(f, self.record.get(f)) for f in INSTANT_FIELDS if isinstance(self.record, dict) and self.record.get(f) is not None] why = ("%s=%r is present but is not a usable instant" % broken[0] if broken else "names no instant field (%s)" % ", ".join(INSTANT_FIELDS)) raise Undated("%s %s: it cannot be read as current" % (path, why)) def as_json(self): return {"path": self.path, "field": self.field, "instant": self.text, "retro_stamped": is_retro_stamped(self.record), "written_at": self.record.get("written_at"), "source": self.record.get(PROVENANCE_FIELD)} def age_seconds(self, now=None): now = now or datetime.datetime.now(datetime.timezone.utc) return (now - self.dt).total_seconds() def is_current(self, mtime): """True when the file this record speaks about is NOT newer than the record's instant. A file newer than the record did not exist when the record was taken, so the record cannot have examined it: that is the whole distinction an instant buys. """ return datetime.datetime.fromtimestamp(mtime, datetime.timezone.utc) <= self.dt def load(path): """The refusal point: read a record as current, or raise `Undated`.""" return Covered(path) _OP_CACHE = {} def _op_text(ops_dirs): """The run's serve ops as one string, CACHED. The first version re-read the whole ops tree on every call, and auditing a few hundred records took minutes -- the cache is not an optimisation of convenience, it is what makes an audit of the corpus-sized record set finish at all. """ key = tuple(sorted(os.path.abspath(d) for d in (ops_dirs or ()))) if key in _OP_CACHE: return _OP_CACHE[key] blob = [] for d in ops_dirs or (): if os.path.isfile(d): files = [d] else: files = [p for p in glob.glob(os.path.join(d, "**", "*"), recursive=True) if os.path.isfile(p)] for p in files: try: blob.append(io.open(p, encoding="utf-8", errors="replace").read()) except OSError: continue _OP_CACHE[key] = "\n".join(blob) return _OP_CACHE[key] def cited(path, ops_dirs=()): """(True, evidence) when the run's own serve ops name this file -- by path tail or by sha256. The discriminator is the adjudicator's, reused rather than re-derived: a file whose bytes were served has a published copy, so rewriting it locally would make the two disagree. """ if not ops_dirs: return False, None blob = _op_text(ops_dirs) if not blob: return False, None posix = os.path.abspath(path).replace(os.sep, "/") tail = "/".join(posix.split("/")[-2:]) if tail and tail in blob.replace("\\\\", "/"): return True, "path tail %s" % tail try: sha = hashlib.sha256(io.open(path, "rb").read()).hexdigest() except OSError: return False, None if sha in blob: return True, "sha256 %s" % sha[:16] return False, None def stamp(path, ops_dirs=(), now=None): """Give an undated record an instant, derived from its own mtime, and say so in the record. Refuses a CITED file (its bytes are published) and a record that already names an instant. The instant is the file's mtime, not the moment of the stamp: an mtime is evidence, a "now" is a narrative, and a retro-fitted record must not be able to present the second as the first. """ rec = json.load(io.open(path, encoding="utf-8")) field, text, dt = instant_of(rec) if dt is not None: return {"path": path, "action": "already-dated", "field": field, "instant": text} hit, ev = cited(path, ops_dirs) if hit: raise Cited("%s was SERVED by this run (%s): adding an instant would make the published copy " "disagree with the local one. Record the exemption instead of stamping." % (path, ev)) mt = os.path.getmtime(path) rec["covered_at"] = datetime.datetime.fromtimestamp( mt, datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") rec[PROVENANCE_FIELD] = ("file mtime, retro-stamped by %s at %s; %s" % (VERSION, stamp_of(now), RETRO_MARK)) with io.open(path, "w", encoding="utf-8", newline="\n") as fh: json.dump(rec, fh, indent=1, sort_keys=True) fh.write("\n") return {"path": path, "action": "stamped", "field": "covered_at", "instant": rec["covered_at"], "source": rec[PROVENANCE_FIELD]} def audit(paths, ops_dirs=()): """Classify records: dated / undated-and-cited (a reasoned exemption) / undated-and-fixable.""" out = [] for p in paths: try: rec = json.load(io.open(p, encoding="utf-8")) except (OSError, ValueError) as exc: out.append({"path": p, "status": "unreadable", "why": str(exc)}) continue field, text, dt = instant_of(rec) if dt is not None: out.append({"path": p, "status": "dated", "field": field, "instant": text, "retro_stamped": is_retro_stamped(rec), "age_seconds": round((datetime.datetime.now(datetime.timezone.utc) - dt).total_seconds(), 1)}) continue hit, ev = cited(p, ops_dirs) out.append({"path": p, "status": "undated-cited" if hit else "undated-fixable", "why": ("served by this run (%s): exempt, its bytes are published" % ev) if hit else "no instant field and never served: stamp it"}) return out # ------------------------------------------------------------------------------- the perimeter # A write site is a place that serialises a JSON object to a file: `json.dump`/`json.dumps` written # to a handle, or a `write()` call whose argument is `json.dumps(...)`. Deliberately text-level. WRITE_SITE = re.compile(r"json\.dumps?\s*\(") # A file GUARDS its record output when it routes through the dated helper or names an instant field # itself. Either is evidence; the first is the contract, the second is a hand-rolled one that at least # makes the record readable. GUARD_EVIDENCE = ("write_dated(", "sahdated.write(", "sahdated import", "import sahdated") INSTANT_NAME = ("covered_at", "written_at", "observed_at") def producers(paths, exempt=None, guard_window=25): """Which files WRITE a JSON record, and whether the write can be undated. A FINDER, not a proof -- it reads source text, so an aliased helper or a record assembled by a library call it does not recognise will be reported UNGUARDED, which is the safe direction: a false alarm costs a reasoned exemption, a miss costs an undated record nobody knows about. What it makes possible is the step advice cannot: the run's own generators can be enumerated and each unguarded site either fixed or EXEMPTED WITH A REASON, so no site is left in an unresolved state. An exemption names the file tail plus a phrase that must still be on the line (not a line number, which drifts -- and an exemption that stops matching a real site while its own line moved must not go quiet). An exemption that matches NOTHING is reported STALE rather than kept: a stale exemption is a licence nobody is watching. """ rows, hits = [], {} for p in paths: try: text = io.open(p, encoding="utf-8", errors="replace").read() except OSError as exc: rows.append({"path": p, "status": "unreadable", "why": str(exc)}) continue lines = text.splitlines() guarded = any(ev in text for ev in GUARD_EVIDENCE) or any(n in text for n in INSTANT_NAME) for n, line in enumerate(lines, 1): if not WRITE_SITE.search(line): continue near = "\n".join(lines[max(0, n - guard_window):n]) routed = any(ev in near for ev in GUARD_EVIDENCE) row = {"path": p, "line": n, "text": line.strip()[:120], "status": "guarded" if (routed or guarded) else "unguarded", "evidence": "calls the dated helper" if routed else ("file names an instant field" if guarded else None), "exempt": None} for e in (exempt or {}).get("exempt", []): tail = e.get("path", "") if p.replace(os.sep, "/").endswith(tail.replace("\\", "/")) \ and e.get("contains") and e["contains"] in line: row["exempt"] = {"why": e.get("why"), "contains": e["contains"]} row["status"] = "exempt" hits[id(e)] = hits.get(id(e), 0) + 1 break rows.append(row) stale = [e for e in (exempt or {}).get("exempt", []) if not hits.get(id(e))] open_sites = [r for r in rows if r.get("status") == "unguarded"] return {"tool": "sahdated.producers", "version": VERSION, "sites": rows, "unguarded": open_sites, "stale_exemptions": stale, "counts": {s: len([r for r in rows if r.get("status") == s]) for s in ("guarded", "exempt", "unguarded", "unreadable")}, "caveat": "text-level finder: an unrecognised writer is reported unguarded, never missed"} # --------------------------------------------------------------------------------------- selftest def _selftest(): ok = True def chk(label, cond, detail=None): nonlocal ok if not cond: ok = False print("%-6s %s%s" % ("ok" if cond else "FAIL", label, "" if detail is None else " " + str(detail)[:160])) def refused(fn, exc_type): try: fn() except exc_type as exc: return str(exc) return None with tempfile.TemporaryDirectory() as td: ops = os.path.join(td, "ops") os.makedirs(ops) dated = os.path.join(td, "dated.json") undated = os.path.join(td, "undated.json") cited_one = os.path.join(td, "cited.json") bad = os.path.join(td, "bad.json") with io.open(dated, "w", encoding="utf-8") as fh: json.dump({"covered_at": "2026-09-23T00:00:00Z", "rows": [1]}, fh) with io.open(undated, "w", encoding="utf-8") as fh: json.dump({"rows": [1, 2]}, fh) with io.open(cited_one, "w", encoding="utf-8") as fh: json.dump({"rows": []}, fh) with io.open(bad, "w", encoding="utf-8") as fh: json.dump({"at": "yesterday-ish", "rows": []}, fh) # the ops record that makes `cited_one` cited -- the run's own serve list, in its own shape with io.open(os.path.join(ops, "serve-1.json"), "w", encoding="utf-8") as fh: json.dump({"op": "serve-files", "path": os.path.abspath(cited_one).replace(os.sep, "/")}, fh) # 1. the refusal, and WHICH reason refused (a gate that only says "it raised" cannot be # mutation-tested -- the lesson `sahcontrol` learned the same day) msg = refused(lambda: load(undated), Undated) chk("an undated record is REFUSED", msg is not None, msg) chk("the refusal names 'no instant field'", msg is not None and "no instant field" in msg, msg) msg2 = refused(lambda: load(bad), Undated) chk("an unparseable instant is REFUSED and quoted back", msg2 is not None and "not a usable instant" in msg2, msg2) # 2. the admission c = load(dated) chk("a dated record loads and reports its field and instant", c.field == "covered_at" and c.text == "2026-09-23T00:00:00Z", c.as_json()) # 3. the arithmetic the instant exists for -- BOTH directions, on real mtimes old = os.path.join(td, "old.txt") new = os.path.join(td, "new.txt") io.open(old, "w").write("x") io.open(new, "w").write("x") os.utime(old, (c.dt.timestamp() - 600, c.dt.timestamp() - 600)) os.utime(new, (c.dt.timestamp() + 600, c.dt.timestamp() + 600)) chk("a file older than the record IS covered by it", c.is_current(os.path.getmtime(old))) chk("a file NEWER than the record is NOT covered by it", not c.is_current(os.path.getmtime(new))) # 4. the citation rule: a served file may not be re-stamped chk("a served record is reported as CITED", cited(cited_one, [ops])[0], cited(cited_one, [ops])[1]) chk("an unserved record is NOT cited", not cited(undated, [ops])[0]) msg3 = refused(lambda: stamp(cited_one, [ops]), Cited) chk("stamping a CITED record is REFUSED (its bytes are published)", msg3 is not None and "SERVED" in msg3, msg3) # 5. the stamp, and its provenance is not passed off as a measurement res = stamp(undated, [ops]) st = load(undated) chk("an unserved undated record IS stamped with its own mtime", res["action"] == "stamped" and st.field == "covered_at", res) chk("the stamp RECORDS that it is a retro-fit, not a measurement", "NOT a measurement" in (undated and st.as_json()["source"] or ""), st.as_json()) chk("stamping twice is a no-op that says so", stamp(undated, [ops])["action"] == "already-dated") # 6. the audit classifies all three, and the two polarities are both present in its output rows = {r["path"]: r for r in audit([dated, undated, cited_one, bad], [ops])} chk("audit: dated -> dated", rows[dated]["status"] == "dated", rows[dated]) chk("audit: undated+served -> undated-cited (a reasoned exemption)", rows[cited_one]["status"] == "undated-cited", rows[cited_one]) chk("audit: unparseable -> undated-fixable, NOT dated", rows[bad]["status"] == "undated-fixable", rows[bad]) chk("audit: the stamped record now reads as dated AND flags its retro-fit", rows[undated]["status"] == "dated" and rows[undated]["retro_stamped"] is True, rows[undated]) # 7. a caller that cannot date its record can still proceed -- by SAYING SO (the transport # scanner's shape), which must be possible or the gate would be unusable. Uses `bad`, # not `undated`: the latter was stamped by case 5, so it is dated by now. try: load(bad) got = None except Undated as exc: got = str(exc) chk("the refusal is an exception a caller can catch and disclose", got is not None) # ---- the WRITE side: an undated record must stop being PRODUCIBLE ----------------------- written = os.path.join(td, "written.json") t0 = datetime.datetime.now(datetime.timezone.utc) write(written, {"rows": [1, 2, 3]}) w = load(written) chk("a record written through the helper always carries an instant", w.field == "covered_at", w.as_json()) chk("the instant is the MOMENT OF WRITING, not a value the caller supplied", abs((w.dt - t0).total_seconds()) < 5, w.text) chk("a write-time record is NOT flagged as a retro-fit", w.as_json()["retro_stamped"] is False, w.as_json()) obs = (t0 - datetime.timedelta(hours=3)).strftime("%Y-%m-%dT%H:%M:%SZ") write(written, {"rows": [1, 2, 3]}, observed_at=obs) w2 = load(written) chk("a caller MAY name an earlier observation, and it is recorded as the covered instant", w2.text == obs, w2.text) chk("...and the moment of writing is recorded BESIDE it, so the lag is visible", w2.record.get("written_at") != obs and w2.record.get("written_at"), (obs, w2.record.get("written_at"))) future = (t0 + datetime.timedelta(days=1)).strftime("%Y-%m-%dT%H:%M:%SZ") msg4 = refused(lambda: write(written, {"x": 1}, observed_at=future), Undated) chk("a FUTURE observed_at is REFUSED (an observation cannot be scheduled)", msg4 is not None and "FUTURE" in msg4, msg4) # atomicity: a record that cannot serialise must leave the target's bytes ALONE keep = json.load(io.open(written, encoding="utf-8")) refused(lambda: write(written, {"rows": set([1, 2])}), TypeError) chk("a failed write leaves the previous bytes untouched (temp + replace, no partial file)", json.load(io.open(written, encoding="utf-8")) == keep and not [f for f in os.listdir(td) if f.startswith(".sahdated-")]) # the two provenances must be DISTINGUISHABLE, or a repaired record would read as a measured # one -- which is the whole reason the mark exists write(written, {"rows": []}) stamp(written, []) # already dated -> no-op, so force the retro-fit path instead retro = os.path.join(td, "retro.json") with io.open(retro, "w", encoding="utf-8") as fh: json.dump({"rows": []}, fh) stamp(retro, []) chk("a write-time record and a retro-fitted one are told apart", load(written).as_json()["retro_stamped"] is False and load(retro).as_json()["retro_stamped"] is True, (load(written).as_json()["source"], load(retro).as_json()["source"])) # ---- the perimeter: a generator that wants to emit an undated record is FOUND -------------- naked = os.path.join(td, "naked.py") routed = os.path.join(td, "routed.py") with io.open(naked, "w", encoding="utf-8") as fh: fh.write("import json\nwith open('out.json', 'w') as fh:\n" " json.dump({'rows': rows}, fh)\n") with io.open(routed, "w", encoding="utf-8") as fh: fh.write("from sahdated import write as write_dated\nwrite_dated('out.json', {'rows': rows})\n") res = producers([naked, routed]) st = {(r["path"].split(os.sep)[-1], r.get("line")): r["status"] for r in res["sites"]} chk("a naked json.dump is reported UNGUARDED", st.get(("naked.py", 3)) == "unguarded", res["counts"]) # The routed file dumps nothing itself -- the helper dumps for it -- so the honest assertion # is that it contributes NO site, not that it "is not unguarded", which was vacuously true (the # check this replaced passed without testing anything, the same shape the census selftest ate). chk("a generator that lets the helper write has NO site at all", not [r for r in res["sites"] if r["path"].endswith("routed.py")], [r["text"] for r in res["sites"]]) hand = os.path.join(td, "hand.py") with io.open(hand, "w", encoding="utf-8") as fh: fh.write("import json\nrec = {'rows': rows, 'covered_at': '2026-09-23T00:00:00Z'}\n" "with open('out.json', 'w') as fh:\n json.dump(rec, fh)\n") res5 = producers([hand]) chk("a hand-rolled dated writer is GUARDED (the safer direction is a false alarm, not a " "miss)", res5["counts"]["guarded"] == 1 and not res5["unguarded"], res5["counts"]) chk("the finder names itself a finder, not a proof", "caveat" in res and res["caveat"]) ex = {"exempt": [{"path": "naked.py", "contains": "json.dump({'rows': rows}", "why": "scratch fixture"}]} res2 = producers([naked, routed], ex) chk("a reasoned exemption closes the site without touching the file", not res2["unguarded"] and res2["counts"]["exempt"] == 1, res2["counts"]) res3 = producers([naked, routed], {"exempt": [{"path": "gone.py", "contains": "x", "why": "obsolete"}]}) chk("an exemption that matches NOTHING is reported STALE, not kept", len(res3["stale_exemptions"]) == 1 and res3["unguarded"], res3["stale_exemptions"]) res4 = producers([naked], {"exempt": [{"path": "naked.py", "contains": "json.dump", "why": "ok"}]}) chk("...and an exemption matching a REAL site is not called stale", not res4["stale_exemptions"] and res4["counts"]["exempt"] == 1, res4["counts"]) undated_ex = os.path.join(td, "ex.json") with io.open(undated_ex, "w", encoding="utf-8") as fh: json.dump({"exempt": []}, fh) chk("an UNDATED exemption list is refused by load (it claims to cover a population)", refused(lambda: load(undated_ex), Undated) is not None) # A MISSING record is the same fact as an undated one -- it cannot be read as current -- and # it must arrive as the SAME catchable refusal. Found live: `producers --exempt ` on a # path that did not exist raised FileNotFoundError out of the one place the contract lives. _missing = os.path.join(td, "no-such-record.json") _why = refused(lambda: load(_missing), Undated) chk("a MISSING record is refused by load as the same catchable refusal, and the refusal names " "the file", _why is not None and _missing in _why, _why) _leaked = None try: load(_missing) except Undated: pass # the refusal the caller is told to expect except BaseException as exc: # noqa: BLE001 -- catching everything is the point of the check _leaked = type(exc).__name__ chk("...and no other exception TYPE reaches the caller (a raw FileNotFoundError would sit " "outside the one contract this module exists to enforce)", _leaked is None, _leaked) chk("VERSION is a string", isinstance(VERSION, str) and VERSION.startswith("sahdated/")) print("\n%s: %s" % (VERSION, "PASS" if ok else "FAIL")) return 0 if ok else 2 def main(argv): if "--version" in argv: print(VERSION) return 0 if not argv or argv[0] == "selftest": return _selftest() cmd = argv[0] rest = argv[1:] ops = [] for i, x in enumerate(rest): if x == "--ops" and i + 1 < len(rest): ops.append(rest[i + 1]) paths = [x for i, x in enumerate(rest) if not x.startswith("--") and not (i > 0 and rest[i - 1] == "--ops")] if cmd == "audit": found = [] for p in paths: found.extend(sorted(glob.glob(os.path.join(p, "**", "*.json"), recursive=True)) if os.path.isdir(p) else [p]) rows = audit(found, ops) counts = {} for r in rows: counts[r["status"]] = counts.get(r["status"], 0) + 1 for r in rows: if r["status"] != "dated": print("%-16s %s -- %s" % (r["status"], r["path"], r.get("why"))) fixable = counts.get("undated-fixable", 0) print("%d record(s): %s" % (len(rows), ", ".join("%s %d" % kv for kv in sorted(counts.items())))) # A VERDICT, not only a listing: an undated-and-fixable record used to be printed beside an # exit code of 0, so no caller could fail on it. `--allow-undated` exists for a caller reading # a foreign tree it has no business stamping, and it says so in the output when it is used. if fixable and "--allow-undated" not in rest: print("VERDICT undated: %d record(s) name no instant and were never served -- stamp them, " "or pass --allow-undated to read a tree you do not own" % fixable) return 2 if fixable: print("VERDICT allowed: %d undated record(s) read under --allow-undated" % fixable) return 0 if cmd == "producers": found = [] for p in paths: found.extend(sorted(glob.glob(os.path.join(p, "**", "*.py"), recursive=True)) if os.path.isdir(p) else [p]) ex = {} for i, x in enumerate(rest): if x == "--exempt" and i + 1 < len(rest): # An exemption list is ITSELF a standing record: it claims to cover the write sites of # a population, so it has to name when it looked. Read through `load`, not # `json.load`, so an undated one is refused instead of quietly licensing sites. ex_path = rest[i + 1] try: ex = load(ex_path).record except Undated as exc: print("REFUSED %s\n %s" % (ex_path, exc)) return 3 res = producers(found, ex) for r in res["sites"]: if r["status"] != "guarded": print("%-9s %s:%d %s" % (r["status"], r["path"], r["line"], (r["exempt"] or {}).get("why") or r["text"])) for e in res["stale_exemptions"]: print("STALE exemption matches nothing: %s %r" % (e.get("path"), e.get("contains"))) print("%d write site(s) in %d file(s): %s" % (len(res["sites"]), len(found), ", ".join("%s %d" % kv for kv in sorted(res["counts"].items()) if kv[1]))) if res["unguarded"] or res["stale_exemptions"]: print("VERDICT open: %d unguarded site(s) without an exemption, %d stale exemption(s)" % (len(res["unguarded"]), len(res["stale_exemptions"]))) return 2 print("VERDICT closed: every write site either routes through the dated helper or is exempted") return 0 if cmd == "stamp": rc = 0 for p in paths: try: r = stamp(p, ops) print("%-14s %s %s" % (r["action"], p, r.get("instant"))) except Cited as exc: print("REFUSED %s\n %s" % (p, exc)) rc = 2 return rc print(__doc__.strip().splitlines()[0]) print("usage: sahdated.py [selftest|audit |producers [--exempt ]|" "stamp ] [--ops ] [--version]") return 2 if __name__ == "__main__": sys.exit(main(sys.argv[1:]))