Skip to content

Describe the finals gate that ships, not the one that broke - #106

Closed
mspinola wants to merge 1 commit into
mainfrom
claude/scheduling-doc-finals-gate
Closed

Describe the finals gate that ships, not the one that broke#106
mspinola wants to merge 1 commit into
mainfrom
claude/scheduling-doc-finals-gate

Conversation

@mspinola

@mspinola mspinola commented Aug 9, 2026

Copy link
Copy Markdown
Owner

WINDOWS_SCHEDULING.md still explained --require-final as a wall-clock check:
norgatedata.last_database_update_time() for both databases against
--final-cutoff, default 20:55. That has not been the mechanism since the gate
went data-driven, and the cutoff flag is accepted-but-ignored in the code. The doc
was describing the version that was replaced precisely because it failed.

It is also load-bearing in a way most stale prose is not. Nobody reads this file
casually. They read it while wiring a producer, and then they build what it says.
It was read exactly that way last week, by someone specifying an equivalent gate
for marketdata: the description was reproduced faithfully, and the 2026-07-27
outage would have been reproduced along with it.

What the paragraph says now

The rule that actually runs, first:

ready := norgate_latest_bar_date > store_latest_bar_date

across the ES / CL / ZC quorum, all of which must have advanced. Then the two
consequences an operator can check against observed behaviour: no trading calendar
is needed, because a weekend and an unsettled session give the same answer; and
Norgate publishes no in-progress bar, so bar presence is already a
settled-session signal.

The 2026-07-27 failure moves into a blockquote on --final-cutoff, kept rather
than deleted. A reader with that flag sitting in an existing wrapper needs to know
it does nothing now, and why taking it out is safe.

Two smaller corrections in the same pass

The restart-on-failure paragraph described each retry as a
last_database_update_time check, naming the dead mechanism in a sentence
otherwise about scheduling.

The testing section said a daytime run "only proves the wrapper resolves". That
stopped being unconditional: under a date comparison a daytime run defers only if
last night captured, so a missed or failed night now self-heals at the next
trigger
rather than waiting for the evening. That is a real operational property
the old wording hid.

Deliberately not touched

docs/design/finals_ready_data_driven.md still describes the cutoff in the present
tense in its Problem section. That is the record of what was true when the change
was argued, and rewriting it would destroy the reasoning the doc exists to
preserve. docs/examples/windows/run-prices.cmd needed no change, being
mechanism-agnostic already.

🤖 Generated with Claude Code

WINDOWS_SCHEDULING.md still explained --require-final as a wall-clock check:
norgatedata.last_database_update_time() for both databases against --final-cutoff,
default 20:55. That has not been the mechanism since the gate went data-driven,
and the cutoff flag is accepted-but-ignored in the code. The doc was describing a
version that was replaced precisely because it failed.

It is also load-bearing in a way most stale prose is not. Nobody reads this file
casually: they read it while wiring a producer, and then they build what it says.
It was read that way last week, by someone specifying an equivalent gate for
marketdata, who correctly reproduced the description and would have reproduced the
2026-07-27 outage with it.

So the replacement paragraph leads with the rule that actually runs, states the
ES/CL/ZC quorum, and gives the two consequences an operator can check against
behaviour: no trading calendar is needed because a weekend and an unsettled
session are the same answer, and Norgate publishes no in-progress bar, so bar
presence is already a settled-session signal. The 2026-07-27 failure moves into a
blockquote on --final-cutoff, kept rather than deleted because a reader with that
flag in an existing wrapper needs to know it does nothing now and why removing it
is safe.

Two smaller corrections in the same pass. The restart-on-failure paragraph
described each retry as a last_database_update_time check, naming the dead
mechanism in a sentence otherwise about scheduling. And the testing section said a
daytime run "only proves the wrapper resolves", which stopped being unconditional:
under a date comparison a daytime run defers only if last night captured, so a
missed or failed night now self-heals at the next trigger instead of waiting for
the evening. That is a real operational property the old wording hid.

The design doc's Problem section still describes the cutoff in the present tense
and is deliberately left alone: it records what was true when the change was
argued, and rewriting it would destroy the reasoning it exists to preserve. The
example wrapper needed no change, being mechanism-agnostic already.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@mspinola

mspinola commented Aug 9, 2026

Copy link
Copy Markdown
Owner Author

Superseded by #105, which rewrote this doc for the post-step-2 world (the nightly job is now marketdata-update --bars --domain futures --require-final) and already carries the corrected data-driven description of the gate. My branch was cut before that landed and would have conflicted on the same paragraph.

Two of the three corrections here are NOT in #105 and are worth keeping, so they follow as a small PR against current main: the restart-on-failure paragraph still names last_database_update_time as what each retry checks, and the daytime-run bullet still says a daytime run can only prove the wrapper resolves, which stopped being unconditional once the gate compared dates.

@mspinola mspinola closed this Aug 9, 2026
@mspinola
mspinola deleted the claude/scheduling-doc-finals-gate branch August 21, 2026 11:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant