The Clock Is Part of the Dataset

Engineering profile: RESEARCH
Toolchain: CPython 3.14 + uv 0.12.5
Quality gate: make check
Declared deviations: no hosted run is claimed; local deterministic gate only.
Stronger local controls: research contract, architecture, frozen candidate review boundary.

Purpose and boundary

This study reconstructs the information available at a decision cutoff when event, availability and correction times differ. It compares valid point-in-time (PIT) reconstruction with a deliberately labelled latest-data oracle in a synthetic constrained top-k decision. It also contains a small frozen ALFRED GDP-vintage diagnostic with source provenance. It does not model real interventions, causal propensity, trading, or real-time release calendars.

Commands

Command	What it does
make setup	Exact sync from uv.lock.
make check	Lock, format, lint, type, tests, bounded deterministic run and manifest validation.
make test	Unit and deterministic integration tests.
make reproduce	Eight-replication bounded evidence smoke path.
make experiment	Canonical 400-replication-per-scenario run and manifest validation.
make clean	Removes bounded generated output and local caches only.

Reconstructing state

event_time is when something happened. availability_time is when its initial report became public. revision_time is when a correction became public. At a cutoff, PIT admits only versions whose known_at is no later than that cutoff; latest ignores this boundary and is an oracle. Unavailable events are counted explicitly rather than filled with a value.

raw records + provenance → temporal normalization → PIT / latest oracle
                                                   → top-k evaluation
                                                   → raw rows, summary, figures, manifest

Evidence layout

• configs/canonical.json — frozen seed and five-scenario grid.
• data/raw/alfred/ — copied official CSV responses; data/provenance/ records URL, as-of label and digest.
• artifacts/canonical/ — generated full replication rows, summaries, figures and content-verified manifest.
• src/clock_dataset/ — ingestion, temporal reconstruction, feature/decision evaluation and runner.

Contract and limits

The exact DGP, information-set definition, controls, metrics, stopping rule and scope are in RESEARCH-CONTRACT.md. The study measures 400 replications across five configurations. It was not varied across real release calendars, missingness, selection into reporting, feedback, non-Gaussian errors, budget size, horizon, causal treatment assignment, or empirical decision contexts. The ALFRED vintage labels are source-specific as-of labels, not asserted exact availability timestamps.

Plain-language model

An event can happen before it is reported, and its report can later be corrected. A fair historical decision uses only what was known then. Using the most recent database state makes the past look easier than it was. The study makes that gap visible under a known generator; it does not tell us the size of the gap in a particular real system.

Review boundary

Local author-side checks are not independent acceptance. Freeze after the canonical run, then request fresh read-only Sonnet forensic review. No publication or push is authorized.

License and data rights

The code, tests, configuration and documentation in this repository are licensed under the MIT License (copyright Joshua de Freitas).

The frozen ALFRED extracts under data/raw/alfred/ and their provenance record (data/provenance/alfred-gdpc1.json) are not covered by the MIT license above — they are third-party data from the Federal Reserve Bank of St. Louis's ALFRED service, sourced from the U.S. Bureau of Economic Analysis's GDPC1 (Real Gross Domestic Product) series. That series is tagged by FRED/ALFRED as "Public Domain: Citation Requested" (verified directly against the series' own tag list at https://fred.stlouisfed.org/series/GDPC1 and the FRED "Public Domain: Citation Requested" series index, 2026-09-03) — consistent with its origin as a U.S. federal government work. Redistribution of the three frozen GDPC1 vintage CSVs in this repository is accordingly permitted, with citation requested. Suggested citation: "U.S. Bureau of Economic Analysis, Real Gross Domestic Product [GDPC1], retrieved from FRED, Federal Reserve Bank of St. Louis; https://fred.stlouisfed.org/series/GDPC1." This determination covers only the exact GDPC1 vintage files frozen here, not FRED/ALFRED data in general — other series carry their own, sometimes restrictive, third-party redistribution terms and must be checked individually before reuse.