Skip to content

Correct how the orphan cost is sized — interval + lag, not interval - #101

Merged
harper-joseph merged 1 commit into
mainfrom
docs/orphan-sizing-correction
Aug 13, 2026
Merged

harper-joseph merged 1 commit into
mainfrom
docs/orphan-sizing-correction

Conversation

@harper-joseph

Copy link
Copy Markdown
Contributor

Docs and comments only; no behavior change. Corrects a number I introduced in #100.

The error

The ~9.5% of fleet throughput figure in the README, the render.orphanSweep description and the orphanSweep.js module comment came from ~40,400 schedule rows ÷ 6h nominal interval = ~6,740/hr against the 71,289/hr ceiling.

That assumes the orphans achieve their nominal 6h cadence. A backlogged queue cannot give them that — and this cluster was ~8.2h behind.

The model

nextRenderTime is stamped at completion, not at the original due time. So a row rendered L behind its due time has its next render set interval after that: the realized cycle is interval + L, and the lag is carried into every subsequent cycle rather than caught up.

At L ≈ 8.2h, orphans on a 6h interval run a ~14h cycle:

claimed actual
orphan render rate 6,740/hr ~2,900/hr
share of 71,289/hr ceiling 9.5% ~4%

Roughly half what was stated.

But the ceiling is the wrong denominator anyway

While the fleet is saturated, what matters is the orphans' share of the work actually being completed. Stretching every class by the same interval + L (PDP 48+8.2 ≈ 56h, catalog 6+8.2 ≈ 14h):

  • PDP ~27,200/hr, real catalog ~5,400/hr, orphans ~2,850/hr → ~35,500/hr total
  • orphans ≈ 8% of it

So the original figure was roughly right for share of work being done, but reached by the wrong route and stated against the wrong denominator. 8% is what deleting them frees, and the benefit compounds slightly: removing that work shortens L, which shortens interval + L for every remaining class.

All three sites now document the interval + lag model itself, not just the corrected number — dividing rows by interval is the natural way to size this, and it's wrong whenever there's a backlog.

664 tests passing, lint and format clean.

…not interval

The '~9.5% of fleet throughput' figure in the README, the config description and
the module comment was derived by dividing ~40,400 schedule rows by the nominal
6h catalog interval and comparing that to the throughput ceiling. That assumes
the orphans achieve their nominal cadence, which a backlogged queue cannot give
them.

nextRenderTime is stamped at COMPLETION, so a row rendered L behind its due time
has its next render set interval after that: the realized cycle is interval + L,
and the lag is carried into every subsequent cycle rather than caught up. At the
8.2h lag measured on that cluster, orphans on a 6h interval ran a ~14h cycle —
~2,900 renders/hr, ~4% of the 71,289/hr ceiling, roughly half what was claimed.

The ceiling is also the wrong denominator while the fleet is saturated. Against
the work it is actually completing, with every class stretched by the same
interval + L, the orphans were ~8% — which is the figure that describes what
deleting them frees, and it is why the sweep is still worth running.

Documents the interval + lag model itself in all three places, since dividing
rows by interval is the natural way to size this and it is wrong whenever there
is a backlog.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the documentation and comments in README.md, configSchema.js, and orphanSweep.js to provide a more precise calculation of the throughput cost of orphan schedule rows. It explains that because nextRenderTime is stamped at completion, any lag L extends the cycle to interval + L, revising the previous flat estimate of ~9.5% throughput to ~4% of the throughput ceiling or ~8% of actual completed work under saturation. There are no review comments, and I have no additional feedback to provide.

@harper-joseph
harper-joseph merged commit 49f9354 into main Aug 13, 2026
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