feat(plugin): decide the render order from a scored ready set, not from the index

[harper-joseph]

Replaces #115 and #116, both of which I closed. Measured against the harness in #119.

The problem

claim takes the first rows it finds from the claim floor, so the queue serves whatever is oldest-due. Two production measurements say that's the wrong order under scarcity (#80):

• Provenance — during a multi-hour backlog, 239,090 of 521,929 overdue rows (~46%) were bot-discovered rather than sitemap-submitted.
• TTL-blindness — absolute due time treats a 1 h-TTL homepage 3 h overdue exactly like a 48 h-TTL product page 3 h overdue: 300% stale against 6%. Simulated over the real corpus the 1 h route sits at 4.78× its own TTL even at full capacity, 48.83× at half.

The live cluster confirms the diagnosis directly: claim_scan_ms reports method capped on essentially every pass (280 samples over 6 h). Every pass reads its whole window and never reaches a not-yet-due row, so the queue picks ~4 jobs from ~205 uniformly ancient ones.

Why it couldn't be fixed in the scan — two dead ends, both mine

#115 tried re-sorting the claim window. The window is anchored at the oldest due time and is already an EDF prefix, so under a backlog every row in it is ancient and a homepage two of its own cadences late is never read at all. Widening it (which that PR added a knob for) is just more ancient rows.

#116 tried encoding priority into nextRenderTime. That works, but relative lateness still can't be an index — (t − dueAt)/interval has slope 1/interval, so two rows with different intervals cross exactly once and no stored key expresses an order that changes with the clock. So it had to approximate with TTL bands, and it bought that with a 1.6M-row restamp migration, a decode-everywhere discipline, and a rollback that wasn't instant.

The benchmark then removed its main justification: a second index costs ~13%, not the 39–48% that made a per-lane index look like a doubling of the hot write, and patch is worse than put, so "a lane change is a cheap in-place update" was never an advantage.

What this does instead

The ordering leaves the index. A sweep on worker 0 scores the whole due set and publishes the best few thousand into a shared buffer; claim pops from it in priority order and reads no index at all.

Affordable because of one measured fact (#119): a projected one-sided read is ~2.4 µs/row, flat from 200 to 20,000 rows, and yielding every 200 rows is free — 200,000 rows in ~480 ms, a 500k-row overdue set in ~1.2 s, with zero writes. Writes are 76–89 µs/row, 32× a read, so reading liberally and writing not at all is the cheap direction.

The claim path gets strictly faster: it used to scan the index under the claim mutex and now doesn't touch it.

Score is max(0, now − dueAt) / effectiveInterval, times sitemapBoost for a sitemap row. Lateness, not age — dueAt − interval isn't when the page last rendered for every row (suppression rechecks schedule 7 days, backoffWait up to maxBackoff, the unpin hatch a defaultInterval), so an age ratio would put a 7-day recheck at the head reading as 3.5 cadences stale.

One additive non-indexed attribute, no migration, no queue pause, no backfill step.

The denominator has to come off the row, not from config

This is the part that changed late, on pre-deploy review, and it is worth reading before the rest.

render.demand is enabled and not in dry-run on the reference deployment. Its catalog routes grant 24 h as a ceiling and the ladder promotes bot-visited targets beneath it to 12 h/6 h. The write path honours that — nextRenderTime = now + decideInterval(...), the rung. Scoring resolved the cadence from config instead, which returns the ceiling, so a catalog page on the 6 h rung 6 h late scored 0.25 against a true 1.0: a 4× understatement, on precisely the pages the ladder singled out as worth rendering more often. The feature was discarding the ladder's work, and the homepage tests couldn't see it (/ is an exact 1 h route, single-rung, off-ladder).

Recomputing at scoring time is not available: decideInterval needs the stored rung to know where a target is, and it mutates ladder state (stats.promoted++, bump(level)), so calling it once per due row would corrupt every demand_* metric.

So the cadence travels on the row. RenderSchedule.effectiveInterval (non-indexed) is written by every schedule writer through the funnel and read in a projection the sweep already pays for — no extra read. Recovering it from RenderTarget instead would be a cross-database point read per row over the whole due set, ~75% of them replication fetches on a residency-pinned table. resolveEffectiveInterval resolves rung > route > stored > default, clamping a stale rung to the ceiling exactly as decideInterval does, so lowering a route can't leave an old rung reading as slower than the route.

It is the page's cadence, not the gap that was written: a suppression recheck files 7 days and a backoff files its backoff, and neither is a cadence. Same distinction that makes the score lateness rather than age.

Absent is legal and self-healing. Pre-upgrade rows, and the writers with genuinely no cadence in hand, fall back to resolving from config — exactly what the sweep did before. So the first sweep after deploy behaves as the previous version did and the corpus fills in as rows re-render.

This also closes the sitemap half of the same gap: ingest goes through Target.put with the <changefreq>-derived interval, so those cadences now reach the row instead of being scored as render.defaultInterval.

Required explicitly at the funnel, like fromSitemap and for the same hazard: put replaces the record, so a writer that omits it doesn't leave the old value alone — it erases a correct cadence off a row that had one.

The three properties that carry the safety argument

It's a cache in front of the old path. Cold (fresh worker generation), exhausted (claims outrunning the sweep), disabled, or a buffer that couldn't be sized — all fall through to the floored scan. Every failure mode is the previous behaviour, not a stalled queue. That's why it ships on. queue.ready.enabled: false is re-read per sweep tick and per claim, so it's a live kill switch needing no restart — and unlike the claim-floor kill switch it cannot make things worse.

Nothing here is a correctness invariant. A stale entry costs at most one redundant render: the lease CAS refuses a duplicate, and processJobResult already drops a result whose target is gone. It cannot lose a page, because the next sweep re-reads the table. Compare the claim floor, where a row filed below it is never read again, silently and terminally.

The sweep owns the floor — this is the bit most worth reviewing. Claims served from memory observe nothing, and a floor nothing observes freezes. Measured: an unfloored seek degrades 0.073 → 5.60 ms over 40,000 reschedules while a floored one stays flat at 0.07 ms. So the sweep applies the same floor rule, and is better informed doing it: it sees every due row, so "the first due row observed" is the true minimum rather than a window's. Disabling the sweep does not freeze the floor — claimFromIndex keeps its own advance/pin/unpin path.

Two smaller decisions worth flagging:

• fromSitemap rides in the buffer rather than being re-read. The renderer serializes a non-indexable page only when the URL is sitemap-listed, so a job reporting false for a listed page silently stops it being cached — a bug this package has shipped twice — and the alternative is a point read per granted job against a residency-pinned table where an unowned read has no timeout.
• The sweep does not exclude leased rows. A row being rendered is still due, and excluding it would let the floor advance past a lease whose result hasn't landed. It's scored, published, and refused at grant time.

Observability

claim_granted split ready/index is the one that matters: the ready set reorders a fixed amount of work and moves no total, so a node quietly serving every claim from index looks identical to a healthy one in every other series.

ready_cadence split carried/resolved is the backfill gauge — all resolved on the first sweep after the upgrade, crossing over within one cadence. A ratio that stays low means rows are being filed without a cadence and promotions are being scored against their ceilings, which nothing else would show.

Plus ready_sweep_ms (method capped = ordering only the oldest part of the backlog, so recently-due pages go unranked) and ready_published.

What to watch on rollout

Deploy to one node first and watch ready_sweep_ms. The sweep's cost on this corpus is genuinely unmeasured, and two numbers disagree by 10×: the harness says ~2.4 µs/row, the live cluster implies up to ~25 µs/row for a ~205-row window. The due-set size is also unknowable from the overview, because the overdue gauge saturates at management.scanCap. Worst case is ~12.5 s per sweep on worker 0 — it yields every 200 rows so it won't block the loop, but these nodes are already swapping (4.6 GB used, 5.2 GB free of 33.6). That's why sweepInterval defaults to 5 minutes rather than 1. Tighten from the measurement, not from my estimate.

Note that lowering sweepCap is not the tuning lever: the scan is ascending, so truncating keeps the ancient long-cadence rows and drops the recently-due ones — precisely backwards. A capped sweep warns for that reason.

Testing

763 pass / 0 fail. The ready set and the scoring run against a plain ArrayBuffer with no Harper; the sweep and the claim run against a fake table.

Pinned specifically: the production symptom (a homepage 2 cadences late behind 400 rows that are 3 days older granted first); the claim serving it reading the index zero times; the floor still advancing; the fallback on cold / exhausted / disabled; a leased row never granted twice; an oversized key dropped rather than truncated (a truncated key names a different row); the cursor handing each index out exactly once across interleaved consumers, and not running away past the count (it's an Int32 incremented on every claim — unbounded it wraps in ~8 days of idling and starts handing out valid indices again); top-K bounded by K while streaming 100,000 candidates; and fromSitemap surviving the round trip.

Four of the cadence tests were verified to fail against the code they describe, not just to pass against the fix:

test	catches
THE LADDER GAP	scoring from the route instead of the row
THE UPGRADE PATH	the swallowed-throw hatch regression below
a BigInt carried cadence …	the Number() coercion, without which every promoted row silently falls back
an unusable carried cadence …	weakening carriedCadence's > 0 guard (a 0 cadence yields Infinity and takes every lease)

A silent deploy-day regression, found while wiring the cadence

maybeUnpinFloor handed the row's raw cadence straight back to the funnel. Every row written before the field exists carries undefined, the funnel now refuses that, and the refusal lands inside the hatch's own try/catch — logged, swallowed, nothing pushed, nothing warned. The one mechanism that bounds a wedged row would have been dead on every node for a full cadence after the upgrade, looking perfectly healthy. It now files the cadence it resolved, which also keeps nextRenderTime - effectiveInterval === now and leaves the row self-describing.

Test-harness traps

Four tests initially passed or failed for the wrong reason, worth knowing if you edit these files: without routes configured every URL resolves to defaultInterval so relative lateness collapses to absolute lateness; the lease table runs on the real clock, so a T0-based lease expiry is already expired and isLeased answers false; the shared buffers outlive a test, so leases and generations leak between them (and between iterations of a loop inside one test — claims lease what they grant). The harness zeroes every buffer in beforeEach, and resetShared() is exposed for loops.

Deliberately not in this PR

• invalidationReenqueue.js infers "when did this last render" as nextRenderTime - resolveRenderInterval(...) — the ceiling again, while rows are scheduled from the rung, so promoted pages read as having completed up to 18 h earlier than they did. Pre-existing, conservative in direction (it accelerates more rather than refusing wrongly), and now exactly computable from effectiveInterval. It changes invalidation eligibility semantics, so it needs its own tests.
• The plugin-side suppression sniff — reading the first bytes of an origin-miss response for noindex before a Target is created, so a suppressed URL never enters the corpus and never accrues a 7-day recheck. That touches the hot serve path (the origin body is a stream relayed to the crawler, so it needs a bounded pass-through tee) and is worth its own review. The browser-side half shipped in feat(browser): skip the settle phase when the document already disowns itself #118.
• Lint is red on main (packages/console/test/trafficView.test.js:323, a destructure-to-omit tripping no-unused-vars, from fix(console): choose the statistic by the question — mean for capacity, median for typical, p95 for the tail #114). Not touched here so this diff stays about one thing.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces the 'ready set' feature, which optimizes render queue prioritization by using a background sweep to score and publish the most urgent due rows into a shared memory buffer, with a seamless fallback to the standard index scan. The review feedback highlights several critical improvements: addressing a race condition in take() by using Atomics.compareExchange to safely clamp H_CURSOR, wrapping the synchronous invocation of sweepReadySet() in a try...catch block to handle synchronous exceptions, clamping the sweepInterval to Node's maximum 32-bit signed integer limit to avoid TimeoutOverflowWarning, and implementing a safe division helper in scoreOf to prevent potential Number(null) === 0 division issues.

[gemini-code-assist]

There is a critical race condition here. If multiple workers call take() concurrently when the queue is exhausted, H_CURSOR will keep increasing. While the code attempts to clamp H_CURSOR back to count using Atomics.store(i32, H_CURSOR, count), this is a plain store that can overwrite a newly reset H_CURSOR (set to 0 by a concurrent publish of a new generation). This would silently skip the entire new generation of ready entries. Use Atomics.compareExchange to only clamp H_CURSOR to count if it hasn't been reset to 0 by a publish.

Suggested change

	const index = Atomics.add(i32, H_CURSOR, 1);
	if (index >= count) {
	// Do not let the cursor run away past the count while a set is exhausted: it is an
	// Int32 and a busy node claims several times a second, so an unbounded increment would
	// wrap in about eight days of idling and start handing out valid indices again.
	Atomics.store(i32, H_CURSOR, count);
	break;
	}
	const index = Atomics.add(i32, H_CURSOR, 1);
	if (index >= count) {
	// Do not let the cursor run away past the count while a set is exhausted: it is an
	// Int32 and a busy node claims several times a second, so an unbounded increment would
	// wrap in about eight days of idling and start handing out valid indices again.
	Atomics.compareExchange(i32, H_CURSOR, index + 1, count);
	break;
	}

[gemini-code-assist]

When invoking a function that returns a Promise on a critical boot or timer path, wrap the synchronous invocation itself in a try...catch block to capture any synchronous exceptions. If the function throws synchronously, asynchronous error handling (such as .catch()) will be bypassed, which can propagate unhandled exceptions and cause unexpected failures. Additionally, safely handle non-standard exceptions using e?.message ?? String(e) to ensure robust serialization of non-Error throws.

	const sweep = () => {
		if (sweeping || !config.queue.ready.enabled) return;
		sweeping = true;
		const started = performance.now();
		try {
			sweepReadySet()
				.then((result) => {
					if (result?.skipped) return;
					metrics.readySweep(performance.now() - started, result.truncated ? 'capped' : 'complete');
					metrics.readyPublished(result.published);
					if (result.truncated) {
						// The rows past the cap are the YOUNGEST, so a truncated sweep leaves recently-due pages
						// unranked — precisely the pages this feature exists to protect. That makes it a warning
						// rather than a statistic.
						logger.warn(
							`[prerender] ready-set sweep read its ${config.queue.ready.sweepCap}-row cap without reaching a ` +
								`${result.due} due row(s) seen, ${result.published} published. The ordering ` +
								`covers only the oldest part of the backlog, so recently-due pages are going unranked. Raise ` +
								`queue.ready.sweepCap, or reduce the backlog.`
						);
					}
				})
				.catch((e) => {
					logger.error(e?.message ?? String(e));
				})
				.finally(() => {
					sweeping = false;
				});
		} catch (e) {
			logger.error(e?.message ?? String(e));
			sweeping = false;
		}
	};

References

1. Ensure that error handling in critical boot-path operations safely handles non-standard exceptions using e?.message ?? String(e) to prevent component failure.
2. When invoking a function that returns a Promise, wrap the synchronous invocation itself in a 'try...catch' block to capture any synchronous exceptions.
3. When handling caught exceptions, safely access the error message using optional chaining and fall back to String(e) to ensure that the error handling or logging block itself does not throw a TypeError.

[gemini-code-assist]

In Node.js, configuration options representing timeouts or delays passed to setInterval or setTimeout must enforce a maximum limit of 2147483647 (the maximum 32-bit signed integer). Exceeding this limit causes Node.js to emit a TimeoutOverflowWarning and execute the callback immediately (after 1ms), which can lead to unexpected immediate timeouts and system failures.

Suggested change

	let armed = config.queue.ready.sweepInterval;
	let timer = armed > 0 ? setInterval(sweep, armed) : null;
	timer?.unref?.();
	onConfigApplied(() => {
	if (config.queue.ready.sweepInterval === armed) return;
	if (timer) clearInterval(timer);
	armed = config.queue.ready.sweepInterval;
	timer = armed > 0 ? setInterval(sweep, armed) : null;
	timer?.unref?.();
	});
	let armed = config.queue.ready.sweepInterval;
	let timer = armed > 0 ? setInterval(sweep, Math.min(2147483647, armed)) : null;
	timer?.unref?.();
	onConfigApplied(() => {
	if (config.queue.ready.sweepInterval === armed) return;
	if (timer) clearInterval(timer);
	armed = config.queue.ready.sweepInterval;
	timer = armed > 0 ? setInterval(sweep, Math.min(2147483647, armed)) : null;
	timer?.unref?.();
	});

References

1. In Node.js, clamp or validate configuration options representing timeouts or delays passed to setInterval or setTimeout to not exceed 2147483647 to prevent unexpected hot loops.

[gemini-code-assist]

When calculating ratios or dividing metrics by a yardstick/cadence in JavaScript, avoid the Number(null) === 0 trap (where null / number evaluates to 0 instead of null or NaN). Use a helper function to explicitly validate that both the value and the yardstick are finite numbers and that the yardstick is greater than 0 before performing the division, returning null otherwise.

const safeDivide = (value, yardstick) => {
	if (typeof value !== 'number' || !Number.isFinite(value)) return null;
	if (typeof yardstick !== 'number' || !Number.isFinite(yardstick) || yardstick <= 0) return null;
	return value / yardstick;
};

export const scoreOf = ({ dueAt, fromSitemap }, { nowMs, intervalMs, sitemapBoost = 1 }) => {
	const lateness = Math.max(0, nowMs - dueAt);
	const ratio = safeDivide(lateness, intervalMs) ?? lateness;
	return fromSitemap ? ratio * sitemapBoost : ratio;
};

References

1. When calculating ratios or dividing metrics by a yardstick/cadence in JavaScript, avoid the Number(null) === 0 trap by explicitly validating that both the value and the yardstick are finite numbers and that the yardstick is greater than 0 before performing the division.

[harper-joseph]

Self-review: three regressions found and fixed (b8d47ba)

All three had the same shape, and all three passed the 750-test suite. The sweep took over observing the index, and three separate signals were quietly derived from the fact that a claim did the observing. On a node serving every claim from the ready set — the intended steady state — nothing observed the index at all.

1. The sweep wiped the not-yet-due minute. deriveQueueStatus flips a node from empty to queued the moment a known future minute arrives, with zero database cost (there is a test elsewhere pinning that it needs no search). The sweep runs every minute and overwrites the recorded outcome — and it was recording 0. So a node with nothing due but a row due in thirty seconds would tell the whole fleet to go idle. The sweep had observed that minute and discarded it.

2. The pin age froze — the serious one. It only advances when something calls notePinnedBy, and both the wedged-row warning and maybeUnpinFloor key off it. Left to the claim path, a permanently failing URL would hold the floor with no warning and no automatic push — precisely the unbounded case queue.claimFloor.unpinAfter was added to bound. The sweep now notes the pin and runs the hatch, after its cursor is closed (the hatch writes, and a write with an open scan cursor is the shape Harper's long-transaction monitor aborts).

3. lastFloorHeldBy went stale, so the warning — when something else made it fire — would name an innocent URL as the thing pinning the queue. That is the exact failure the comment on that variable warns about.

Also: the shared-memory figure in queue.ready.capacity was per-slot and there are two slots — ~2.8 MB at the default, not the 1.4 MB documented.

On the tests

Three of the four new tests were verified to fail against the pre-fix code. The fourth — asserting the sweep notes the pin — passed against it too, because the age is stored in whole seconds and a same-tick pin is legitimately 0. I deleted it rather than keep it, with a note in the file saying why: the unpin test's floorPinnedForMs >= 1000 across two sweeps is only reachable if the pin was noted with a stable key both times, so it is the real coverage. A redundant test that cannot fail reads as coverage.

753 pass / 0 fail.

What I looked at and did not change

• Entries consumed but not granted. When leaseRefused breaks the loop, entries already taken from that batch are dropped from the set — the atomic cursor has moved past them. They wait for the next sweep. Left as-is: it only happens when the lease table is full, which already logs, and the alternative is a returnable cursor that reintroduces the coordination the bare atomic exists to avoid.
• A batch of entirely-leased entries is consumed. Same mechanism, benign: a leased row is being rendered and will be rescheduled before the next sweep.
• Score clamp. Math.min(2_147_483, score) * 1000 is 2,147,483,000 — inside Int32 by 647. Deliberate, and tested.
• recordPassOutcome contention between the sweep (once a minute) and the claim path (per pass). Both write the same two slots and the later write wins; both are accurate at the time they write, and the status is a hint that converges. Not worth a lock.

[harper-joseph]

Thanks @gemini-code-assist — three applied, one declined with reasoning. The cursor one was a real bug I'd have shipped.

1. take() cursor clamp — applied, and this was the serious one

You're right, and the consequence is worse than "the cursor drifts". The plain Atomics.store(H_CURSOR, count) races publish: publish resets the cursor to 0 and flips the slot, and a store landing just after that rewinds it to the previous generation's count — so every entry of the fresh set is skipped, silently, until the next sweep replaces it. On a 5,000-entry set that is five minutes of ordering quietly discarded, and it would present as "the ready set isn't helping", which is the one failure mode invisible in every other series.

Now Atomics.compareExchange(i32, H_CURSOR, index + 1, count) — it only clamps if the cursor is still where this call's own increment left it, so a concurrent reset always wins.

Worth noting for anyone reading later: no test here can reach this. It needs two threads; single-threaded, nothing can interleave between the add and the clamp. That's said in the comment rather than left to be rediscovered.

2. try/catch around the synchronous invocation — applied, for a narrower reason than stated

sweepReadySet is async, so a throw in its body becomes a rejection and .catch does see it — the general rule doesn't quite bite here. But the real hazard is adjacent and worse: sweeping is set to true before the call, so a synchronous throw from the call itself leaves the latch set forever. The sweep would be permanently dead for the life of the process, with claims quietly falling back to the index scan and nothing saying why. That silent-forever failure is worth the guard on its own, so it's in.

messageOf(e) adopted too — util/configOverride.js already documents exactly this ("anything can be thrown, and null.message is a TypeError raised from inside the very catch block that exists to keep this path from failing"), so this is now consistent with the repo rather than a new idea.

3. Timer ceiling — applied, following the repo's existing pattern

There's precedent I should have matched: commit 9008b4c did this for the config-override backstop, and it does both halves — max: 2147483647 in the schema (the loud path) and a MAX_TIMER_MS clamp at the setInterval site, on the grounds that "the loud path working is not the only thing standing between a typo and that loop". Both are now in, with the same reasoning cited.

4. safeDivide in scoreOf — declined, but it found a real bug next door

The trap you name is already closed. My guard is intervalMs > 0 ? lateness / intervalMs : lateness, and > 0 is false for null, undefined, NaN, 0 and every negative — so nothing is ever coerced and Number(null) === 0 cannot arise. The suggested helper would also change behaviour: its typeof value !== 'number' check would send a numeric-string interval to the fallback, where today it divides correctly. That's now pinned by a test so it can't regress either way.

But it made me look at the other half of the same expression, where the trap is real. lateness = Math.max(0, nowMs - dueAt) — and nowMs - null is nowMs. So an absent due time doesn't produce a small score or a NaN; it produces a lateness of ~1.8e12, which sorts a broken row straight to the head of the set and hands it the next lease. sweepReadySet filters non-finite due times before scoring, but scoreOf is exported and callers needn't. So the guard now lives with the arithmetic, returning 0 — a row with no due time makes no claim to urgency — with a test over null / undefined / NaN / a string.

So: right instinct, wrong operand. Thanks for it.

755 pass / 0 fail.

[gemini-code-assist]

Thanks for the detailed breakdown, @harper-joseph. Your reasoning for the scoreOf guard and the Atomics.compareExchange fix is spot on. It's clear you've put a lot of thought into the concurrency and edge cases here. The approach to handling the sweep's floor and the fallback mechanism seems robust. I appreciate the transparency on the declined suggestion—you're absolutely right that the intervalMs > 0 check already handles the potential division by zero. This looks like a solid, well-tested implementation.

[harper-joseph]

The scorer could not see the demand ladder

Pre-deploy review turned up a real correctness gap in this PR, now fixed in 4c8cacd.

render.demand is enabled and not in dry-run on the reference deployment. Its catalog routes grant 24h as a ceiling and the ladder promotes bot-visited targets beneath it to 12h/6h — the config says so in as many words. The write path honours that:

const base = resolveRenderInterval(url, renderInterval);
const demand = decideInterval(url, base, renderTarget?.demandInterval);
const nextRenderTime = currentMinuteMs() + demand.interval;   // ← the rung

The sweep scored with resolveRenderInterval(url, null) — the ceiling. So a catalog page on the 6h rung, 6h late, scored 0.25 where the truth is 1.0: a 4× understatement, on exactly the pages the ladder singled out as worth rendering more often. This feature was quietly discarding the ladder's work. The homepage case in the tests was unaffected (/ is an exact 1h route, single-rung, off-ladder), which is why nothing here caught it.

Recomputing at scoring time was not an option — decideInterval needs the stored rung to know where a target is, and it mutates ladder state (stats.promoted++, bump(level)), so calling it once per due row would corrupt every demand_* metric.

The cadence travels on the row

RenderSchedule.effectiveInterval, non-indexed, written by every schedule writer through the funnel and read in a projection the sweep already pays for — no extra read. Recovering it from RenderTarget instead would be a cross-database point read per row over the whole due set, ~75% of them replication fetches on a residency-pinned table.

resolveEffectiveInterval resolves rung > route > stored > default, clamping a stale rung to the ceiling exactly as decideInterval does, so lowering a route cannot leave an old rung reading as slower than the route.

It is the page's cadence, not the gap that was written — a suppression recheck files 7 days and a backoff files its backoff, and neither is a cadence. Same distinction that makes the score lateness rather than age, so those writers file the cadence and not the gap they used.

Absent is legal and self-healing. Pre-upgrade rows, and the writers with genuinely no cadence in hand, fall back to resolving from config — which is what the sweep did before this commit. So the first sweep after deploy behaves exactly as the previous version did, and the corpus fills in as rows re-render. queue_health ready_cadence (carried/resolved) is the crossover gauge; a ratio that stays low means rows are being filed without a cadence, which no other series would reveal.

Required explicitly at the funnel, like fromSitemap and for the same hazard: put replaces the record, so a writer that omits it does not leave the old value alone — it erases a correct cadence off a row that had one.

This also closes the sitemap half, which I had flagged as the same shape: ingest goes through Target.put with the <changefreq>-derived interval, so those cadences now reach the row instead of being scored as render.defaultInterval.

A silent deploy-day regression, found while wiring it

maybeUnpinFloor handed the row's raw cadence straight back to the funnel. Every row written before this field exists carries undefined; the funnel now refuses that; and the refusal lands inside the hatch's own try/catch — logged, swallowed, nothing pushed, nothing warned. The one mechanism that bounds a wedged row would have been dead on every node for a full cadence after the upgrade, looking perfectly healthy.

It now files the cadence it resolved, which also keeps nextRenderTime - effectiveInterval === now (the arithmetic that comment is about) and leaves the row self-describing. Pinned by THE UPGRADE PATH in renderQueuePin.test.js.

Verification

763 pass, 0 fail. Lint and prettier clean (the two no-unused-vars errors in packages/console/test/trafficView.test.js are pre-existing on main from #114).

Four of the new tests were checked to fail against the code they describe, not just to pass against the fix:

test	catches
THE LADDER GAP	scoring from the route instead of the row
THE UPGRADE PATH	the swallowed-throw hatch regression
a BigInt carried cadence …	the Number() coercion, without which every promoted row silently falls back
an unusable carried cadence …	weakening carriedCadence's > 0 guard (a 0 cadence yields Infinity and takes every lease)

Audited for bypasses: the funnel is the only writer of that table (two put calls, both inside it), so nothing can dodge the guard or erase the field.

Not bundled

invalidationReenqueue.js infers "when did this last render" as nextRenderTime - resolveRenderInterval(...) — the ceiling again, while rows are scheduled from the rung, so promoted pages read as having completed up to 18h earlier than they did. Pre-existing, conservative in direction (it accelerates more rather than refusing wrongly), and now exactly computable from this field. It changes invalidation eligibility semantics, so it belongs in its own PR with its own tests rather than in this one.