Status summary

Project status summary — 2026-07-28

Phases 0-3 complete and committed. Phases 4 (domain pipelines), 5 (scout agent), and 6 (publish) not started. This is a snapshot, not a finished product — written to answer four questions plainly: what exists, what data from it can be trusted, what the limitations are, and how to use it well.

What has been built

• Scaffolding: git repo scoped correctly to this directory (the home directory itself turned out to already be an untouched, unrelated git repo — left alone), Python venv, dependencies, .env/.gitignore handling.
• Phase 0 — capability survey (findings/00-capability-survey.md): a queried, evidence-based inventory of what FactIQ actually contains, not what its docs claim. Covers US agencies, SEC filings, China/India/Korea trade & macro, all 27 EU Comext reporters, satellite/geo signals, earnings transcripts, market data, and the operational envelope (row caps, rate limits, error behavior).
• Phase 1 — vintage probe (findings/01-vintage-probe.md): the gate finding. FactIQ is confirmed not vintage-aware — 10/10 test periods matched the current-revised value, none matched the original print, and a direct test proved the underlying update is destructive (the pre-revision value is gone, not superseded). Fully re-runnable: python -m src.validation.vintage_probe.
• Phase 2 — storage layer (src/storage/, src/sources/): an append-only Parquet archive keyed by (source, harvest_date), with two distinctly-named DuckDB resolution functions (value_as_of, current_best_value), and two working source implementations (FredAlfredSource live REST; FactIQSource via a staged MCP-pull JSON, since FactIQ has no standalone API). 9 tests passing, built on the real Phase 1 numbers as ground truth.
• Phase 3 — harvester (src/harvest/): a single entry point (python -m src.harvest.run_harvest) that is idempotent, resumable (verified with a real synthetic failure/resume scenario, not just unit tests), rate-limit-aware with backoff, and wires the drift check into every run. One real harvest is committed (2026-07-28): 2 FRED series + 3 FactIQ series archived successfully, drift check clean. Windows Task Scheduler instructions are documented (run_harvest.bat), but the scheduled task has not actually been registered yet — what exists is the mechanism and the instructions, not a running unattended cron.

What data can be reliably taken from this right now

1. The capability survey facts (Phase 0) — trustworthy as of the query date (2026-07-27/28); re-verify before relying on anything if much time has passed, since FactIQ's own coverage can change.
2. The vintage verdict itself (Phase 1) — highly reliable, and cheap to re-check: the comparison script is committed and re-runnable against live ALFRED data at any time.
3. Anything archived from 2026-07-28 onward, for the 5 currently configured series (PAYEMS, A191RL1Q225SBEA via FRED; bls.CES0000000001, bea.nipa|A191RL|T10301, china_customs.china_customs_prelim_total_export_cny via FactIQ) — this is the only FactIQ-derived data this project will ever have with a genuine point-in-time guarantee, because harvest_date is the sole mechanism that makes that true.
4. FRED/ALFRED data generally — reliable point-in-time back through ALFRED's real vintage history (decades), independent of FactIQ entirely. This is the trustworthy backbone for any US series with a FRED equivalent, and the control against which everything else should be checked.

Everything before 2026-07-28 sourced through FactIQ is not point-in-time data, no matter how it's presented — it is today's revised figures wearing a historical date. There is no way to fix this retroactively; it can only get better going forward as the archive accumulates.

What the vintage finding does and does not rule out

It is easy to over-read Phase 1 as "this project produces no usable data." That's too pessimistic. The finding is specific: retroactively backtesting FactIQ's own revision-prone macro series (GDP, payrolls, and the like) against periods before this project started harvesting is not trustworthy, full stop. That specific use is dead. Several other uses are not:

• Going forward, from 2026-07-28 on, this is real point-in-time data. harvest_date is exactly the mechanism that makes that true — every day the harvester runs, today's snapshot becomes tomorrow's trustworthy history. A live monitoring or divergence-detection system built from here forward is not compromised by the Phase 1 finding at all, and the useful window only grows with time.
• FRED/ALFRED gives genuinely vintage-correct US macro data back decades. Any domain needing a real historical US backtest (Domain D, US energy) can anchor its macro leg on FRED and lean on FactIQ only for the breadth FRED doesn't have (transcripts, satellite, market data, non-US series) where revision isn't the concern.
• Most of the four planned domains are structural divergence plays, not "was the number revised" plays. Official stats vs. satellite ground truth, mirror-statistic cross-checks, a known lead/lag relationship (Korea semiconductor exports vs. the global cycle) — these come from comparing sources against each other, not from trusting FactIQ's own historical revision path. The vintage problem matters far less there than it does for "did GDP beat or miss its advance estimate."
• Satellite, customs, and transcript data mostly aren't revised the way headline macro is — a fire detection or a nighttime-lights reading isn't restated the way GDP is. This makes that data more usable as-is, historically, than the macro series Phase 1 tested — but this is a reasonable assumption carried over from how those data types generally behave, not something this project has specifically vintage-tested the way it tested payrolls and GDP. Treat it as likely, not proven.

So: no usable retroactive macro backtest through FactIQ. Yes to forward monitoring, FRED-anchored macro history, cross-source structural signals, and (provisionally) non-revised data types. The project is not dead; one specific, important use of it is.

Limitations — stated plainly

• Only 5 series are configured right now (2 FRED + 3 FactIQ) — this is proof-of-mechanism scale, not the breadth of the Phase 0 survey. Adding FRED series is trivial (src/harvest/config.py); adding FactIQ series adds daily operator burden (see next point).
• FactIQ's daily harvest is not fully automated. It has no standalone REST API — a Claude Code session has to run the MCP queries and stage JSON files before the scheduler runs. Unattended daily cron today only really covers the FRED leg; the FactIQ leg will fail loudly (correctly) without that manual step. This is the single biggest operational gap.
• No historical backfill exists or can exist for FactIQ series. The archive only starts accumulating real vintages from the day it started running. Any analysis wanting FactIQ-sourced history before 2026-07-28 is working with revised data, full stop.
• Known, confirmed data gaps from Phase 0 that will directly constrain Phase 4 domains: Form 4 and 13F absent from SEC entirely; Korea's 10-day/20-day provisional export releases absent (weakens the Korea nowcast domain's premise); the specific Yunnan hydropower reservoirs needed for the aluminium-curtailment story are absent (only an unrelated natural lake resolves) — Domain A needs a substitute proxy, not reservoir levels as originally scoped; USDA ERS is ~3.5 years stale.
• A bad FactIQ series_id returns zero rows silently rather than erroring — every future query against FactIQ (domain pipelines included) must check row counts explicitly; an empty result is not proof of "confirmed zero."
• The drift log has exactly one clean entry. That proves the mechanism works, not that FactIQ is stable — it needs weeks to months of accumulation before an absence of restatements means anything.
• No analytical output exists yet. Phases 4-6 (domain pipelines, scout agent, published site) haven't started. Nothing here yet says anything about China industrial activity, EU gas flows, Korea's trade cycle, or US energy — this is validation and plumbing, not the research payload.
• FactIQ replied (2026-08-03), confirming the finding at the source level — no pre-revision retention, refreshes delete and reinsert rows, no unexposed vintages, no point-in-time querying, and no commitment to build any of this in the near term (see the addendum in findings/01-vintage-probe.md). This changes nothing architecturally — harvest_date was always built as the only insurance regardless of their answer — but it upgrades the verdict from "confirmed by testing" to "confirmed by testing and by the vendor." No further reply is expected.

Best way to use this, now and once complete

• Right now: treat Phase 0/1 as the authoritative reference for what FactIQ can and can't do — useful for scoping any other decision, and for the FactIQ conversation itself.
• Never blend the two resolution functions. current_best_value is "what does the world look like today" context only. value_as_of (which only means anything for data harvested after 2026-07-28) is the only legitimate input to anything calling itself a backtest against FactIQ-sourced macro history. For US macro backtests specifically, prefer FRED/ALFRED's own vintages over waiting for the FactIQ archive to accumulate — it's already decades deep.
• Expand series coverage deliberately, not exhaustively — every FactIQ series added is a recurring manual staging cost until the API question is resolved, so prioritize by what Phase 4's domains actually need.
• Let the archive accumulate before trusting any FactIQ-sourced backtest — the useful point-in-time window only grows from here; there is no shortcut to more history.
• When Phase 4 lands: read every domain's antithesis and caveats section as seriously as its headline result, especially where Phase 0 already found a specific gap (Korea provisional releases, Yunnan reservoirs) — those should lower confidence in specific domains by design, not be treated as solved.
• When Phase 5/6 land: the scout queue and published site are for surfacing candidates for human review, never for automated decisions — consistent with agents proposing and never calculating.
• Treat FactIQ as adversarial-by-default until they answer the mechanics questions, and re-run the vintage probe periodically regardless of their answer — it's fully scripted and cheap, and it's the only way to catch FactIQ quietly changing behavior later.