From 527cf5cffb7d4676cefb3b276908659831b6a5ad Mon Sep 17 00:00:00 2001 From: Tomasz Dobrowolski Date: Tue, 25 Aug 2026 21:09:58 +0300 Subject: [PATCH 1/2] docs: document the data_as_of response envelope Every FlashAlpha API response carries data_as_of, reporting when each upstream feed last delivered to the node that answered, plus endpoint_version identifying the deployment. Nine feeds are reported separately - equity and index spot, their option chains, futures and futures options, the classified trade tape, settled open interest, and the macro series - because they arrive over different pipes and fail independently. An index chain can be current while the index level behind it is not, and one timestamp cannot express that. The section covers how to read it, not just what it is: each feed against its OWN cadence rather than against as_of. Settled open interest dated to the previous session's close is correct, because it is published once per session - on a Monday the newest figure that exists is Friday's. An options feed an hour behind during the regular session is not. A null means that node has not seen that feed, not that it is broken. The limit is stated alongside the claim: the field evidences that a feed delivered recently, not that every contract in a chain is equally current. Documentation only. No code changes. --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index 18e36bb..0bec503 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,44 @@ Key skew metrics: --- +## Data provenance: `data_as_of` + +Every FlashAlpha API response carries `data_as_of`, reporting when each upstream feed last +delivered to the node that answered, plus `endpoint_version` identifying the deployment +that produced it. + +```json +"endpoint_version": "2026.08.25", +"data_as_of": { + "node": "fa2", + "equity_feed": "2026-08-25T18:48:58.204Z", + "equity_options_feed": "2026-08-25T18:48:57.900Z", + "index_feed": null, + "index_options_feed": null, + "futures_feed": null, + "futures_options_feed": null, + "flow_feed": "2026-08-25T18:48:55.100Z", + "oi_feed": "2026-08-22T20:00:00.000Z", + "macro_feed": "2026-08-25T18:45:00.000Z" +} +``` + +Spot and options are reported separately because they arrive over different pipes and fail +independently - an index chain can be current while the index level behind it is not, and +one timestamp cannot express that. + +Read each feed against its **own cadence**, not against `as_of`. `oi_feed` at the previous +session's close is correct: settled open interest is published once per session, so on a +Monday the newest figure that exists is Friday's. An options feed an hour behind during +the regular session is not correct. A `null` means that node has not seen that feed, not +that it is broken. + +The field evidences that a feed delivered recently. It does not assert that every contract +in a chain is equally current: an illiquid strike may not have quoted for hours while its +feed is healthy. + +Full reference: + ## Realized vs Implied Volatility and the Vol Risk Premium **Realized volatility (RV)** is the standard deviation of log returns over a historical lookback window, scaled to annual terms. Common estimators include close-to-close, Parkinson (high-low), Garman-Klass, and Yang-Zhang. See [theory/realized_volatility_estimators.md](theory/realized_volatility_estimators.md) for a comparison. From 5673c31adbdd51dd7d21bf7c68fc012c4cc9ab08 Mon Sep 17 00:00:00 2001 From: Tomasz Dobrowolski Date: Wed, 26 Aug 2026 13:24:14 +0300 Subject: [PATCH 2/2] docs: fix impossible OI dates, wrong imports, and an overclaim Review found three defects that were teaching the wrong thing. The sample OI timestamp was 2026-08-22T20:00:00Z presented as the prior session close for a 2026-08-25 response. 2026-08-22 is a Saturday, so no session closed then; the prior close for Tuesday the 25th is Monday the 24th. An impossible timestamp in a provenance example is worse than no example, because the whole point of the field is teaching people - and models - what a correct market calendar looks like. Corrected in 15 files, docs and test fixtures alike. The TypeScript import named a package that does not exist. The live package is `flashalpha` and the replay package is `flashalpha-historical`, not `@flashalpha/sdk` and `@flashalpha/historical`. Both were wrong; only one had been reported. "Every successful response carries data_as_of" was true of the HTTP API but not of this client. A few endpoints return a bare JSON array, where the API puts the envelope in the X-Data-As-Of and X-Endpoint-Version headers instead - and these clients return the parsed body only, so the envelope is not reachable through those methods at all. The claim is now scoped to JSON-object responses and the array case is documented as the limitation it is rather than implied to work. On the replay service every endpoint returns an object, so the unscoped claim holds there and says so. AGENTS.md gains a freshness section, which is the file an agent actually reads as operating rules and mentioned none of this. It maps each kind of call to the feeds that answer it, so a null on an unrelated feed is not treated as a problem; states that timestamps are UTC instants to compare rather than parse; judges staleness against each feed's cadence rather than the wall clock; and - the part that was missing entirely - says that a null on a feed you depend on means freshness is UNKNOWN, so the answer must be qualified or declined rather than presented as current. It also warns that node can change between calls, so timestamps must not be diffed across calls, and that endpoint_version is opaque deployment metadata rather than a semver to parse. Four .csproj.lscache files were committed by an over-broad git add in the first commit. They declare themselves disposable; now untracked and ignored. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0bec503..9e408a1 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ that produced it. "futures_feed": null, "futures_options_feed": null, "flow_feed": "2026-08-25T18:48:55.100Z", - "oi_feed": "2026-08-22T20:00:00.000Z", + "oi_feed": "2026-08-24T20:00:00.000Z", "macro_feed": "2026-08-25T18:45:00.000Z" } ```