/health: min-cover status per tier (replaces rung-count pivot)

Bumps gbfs/api's pyrmts pin c1f1f1b → f96532b — the old pin predates
9d16761 ("gap-discovery: emit minimal cover"), so its
\`listExpectedShards\` enumerated every rung × every period (full
inventory). The cascade worker was already on the min-cover impl;
the api worker was the straggler.

\`getPyramidsHealth\` now reports what actually matters per tier:
the min-cover of \`[genesis, now)\` — max-rung tiles over closed
history + trailing finer-rung "dust" — rather than raw per-rung shard
counts (which mostly surfaced stale intermediates that never re-enter
the cover):

  - max rung present/expected + per-dust-rung present/expected
  - \`firstMissingPeriod\` — oldest cover gap
  - \`dustAgeSec\` — time since last max-rung boundary
  - \`staleShardCount\` — indexed shards outside the cover (GC candidates)
  - per-pyramid \`allComplete\` / \`totalMissing\` / \`totalStale\`

\`AVAIL_GENESIS\` exported from \`avail_geo.ts\` (kept in sync with the
cascade worker's copy).

FE \`PyramidsSection\` rewritten to one row per tier: ✓/✗, max-rung
N/M, dust breakdown, dust age, stale count, first-missing timestamp.

First render against prod D1 immediately surfaced a real gap: all 10
finest tiers' \`firstMissingPeriod\` = today's midnight UTC — the
cascade hasn't produced the 2026-07-09T00:00 boundary shards
(debugging separately).

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

Author: ryan-williams

gbfs/api/package.json

@@ -18,8 +18,8 @@
     "@rdub/file-tree": "https://github.com/runsascoded/file-tree#d3476b0d2cb398197f3a1383f41fe3b0216be39f",
     "@rdub/thrds": "https://github.com/runsascoded/thrds#ts-dist",
     "hyparquet": "https://github.com/runsascoded/hyparquet#0f355ea5a37dcb9b29a43e33a3d45ce660c80798",
-    "pyrmts": "https://github.com/runsascoded/pyrmts#c1f1f1bcd5854519c41032d03d9bed5d3d1e76b3&path:/js/packages/pyrmts",
-    "pyrmts-cfw": "https://github.com/runsascoded/pyrmts#c1f1f1bcd5854519c41032d03d9bed5d3d1e76b3&path:/js/packages/pyrmts-cfw",
-    "pyrmts-geo": "https://github.com/runsascoded/pyrmts#c1f1f1bcd5854519c41032d03d9bed5d3d1e76b3&path:/js/packages/pyrmts-geo"
+    "pyrmts": "https://github.com/runsascoded/pyrmts#f96532b4ac35d2934b0c256d91a8dce4ba7744b2&path:/js/packages/pyrmts",
+    "pyrmts-cfw": "https://github.com/runsascoded/pyrmts#f96532b4ac35d2934b0c256d91a8dce4ba7744b2&path:/js/packages/pyrmts-cfw",
+    "pyrmts-geo": "https://github.com/runsascoded/pyrmts#f96532b4ac35d2934b0c256d91a8dce4ba7744b2&path:/js/packages/pyrmts-geo"
   }
 }

gbfs/api/pnpm-lock.yaml

@@ -92,6 +92,12 @@ export const TIERS: Tier[] = [
 const KEY_TEMPLATE = 'avail-v3/{tier}/{shard}/{period}.parquet';
 const RESOLUTIONS = [15, 14, 13, 12, 11, 10];
 
+/** avail-v3 genesis: earliest 5-min-aligned UTC timestamp intersecting any
+ *  materialized shard. Used by the /health min-cover computation. Keep in
+ *  sync with `gbfs/cascade/src/avail3/cascade.ts` — same value must hold on
+ *  both workers so cover math agrees on the closed-history region. */
+export const AVAIL_GENESIS = new Date('2026-04-07T01:15:00Z');
+
 function makeBaseProps(bucket: R2Bucket): Omit<GeoPyramid, 'dims'> {
 	return {
 		storage: parquetBackend(r2Storage(bucket)),

gbfs/api/src/avail_geo.ts

@@ -7,6 +7,7 @@
  *
  * See `specs/gbfs-health-page.md` for the surfaced shape.
  */
+import { floorToSpan, listExpectedShards, parseDuration, type Pyramid } from 'pyrmts';
 
 interface R2Object {
 	key: string;
@@ -57,27 +58,46 @@ export interface CascadeHealth {
 	expectedCells: Array<{ agg: string; cons: string; deployed: boolean }>;
 }
 
-/** Per-(tier, shard_dur) status for a unified-shard-ladder pyramid
- *  (avail-v3, rides-v3). One row per declared ladder rung. */
-export interface PyramidShardStatus {
+/** Per-rung slot in a tier's current min-cover of `[genesis, now)`. In
+ *  equilibrium each tier's min-cover is mostly max-rung tiles filling the
+ *  closed-history region `[genesis, floor(now, max_rung))`, plus a small
+ *  "dust" of finer-rung tiles filling `[floor(now, max_rung), now)`. A rung
+ *  entry counts how many shards the min-cover places at that rung and how
+ *  many actually exist in the ShardIndex. */
+export interface PyramidCoverRung {
+	shardDur: string;
+	role: 'max' | 'dust';
+	expected: number;   // shards the min-cover requires at this rung
+	present: number;    // of those, how many are in D1
+}
+
+/** Per-tier min-cover status. `complete` iff every rung's `present === expected`. */
+export interface PyramidTierCoverStatus {
 	tier: string;
-	shardDur: string;        // e.g. '5min', '1d', '4320d'
-	shardCount: number;      // # shards recorded in ShardIndex
-	earliestPeriodStart: string | null;   // ISO ms
-	latestPeriodEnd: string | null;       // ISO ms
-	watermarkEnd: string | null;          // pyramid_watermarks.latest_period_end
+	bin: string;
+	maxRung: string;
+	rungs: PyramidCoverRung[];               // ordered oldest → newest
+	totalExpected: number;
+	totalPresent: number;
+	complete: boolean;
+	firstMissingPeriod: string | null;       // ISO of oldest missing cover shard, if any
+	lastMaxBoundary: string;                 // ISO of floor(now, max_rung) — dust head
+	dustAgeSec: number;                      // now - lastMaxBoundary, in seconds
+	staleShardCount: number;                 // present shards NOT in current min-cover
 }
 
-export interface PyramidStatus {
+/** Per-pyramid roll-up. `allComplete` iff every tier's min-cover is satisfied. */
+export interface PyramidCoverStatus {
 	name: string;            // 'avail' / 'rides' etc.
-	tiers: Array<{
-		tier: string;
-		bin: string;
-		shards: PyramidShardStatus[];     // one per declared rung
-	}>;
+	genesis: string;         // ISO — cover computed over [genesis, now)
+	now: string;             // ISO snapshot time
+	tiers: PyramidTierCoverStatus[];
+	totalMissing: number;    // sum of (expected - present) across tiers
+	totalStale: number;      // sum of staleShardCount across tiers
+	allComplete: boolean;
 }
 
-export type PyramidsHealth = PyramidStatus[];
+export type PyramidsHealth = PyramidCoverStatus[];
 
 /** Recency of `s3://tripdata` — the upstream Citi Bike monthly publish.
  *  Sourced from `tripdata/latest.json` in R2, refreshed every `tripdata.yml`
@@ -313,14 +333,17 @@ interface RawTripdataSummary {
 	total_zips: number;
 }
 
-/** Snapshot per-(tier, shard_dur) status for unified-shard-ladder
- *  pyramids. Reads D1 directly (`pyramid_shards` for counts/extents,
- *  `pyramid_watermarks` for watermarks). Tier declarations come from
- *  `avail_geo.ts`'s `TIERS`; tracks the same ladders the api worker
- *  serves queries from.
+/** Snapshot per-tier min-cover status for unified-shard-ladder pyramids.
+ *  Reads `pyramid_shards` directly (all rows: `tier, shard_dur,
+ *  period_start`), computes the expected min-cover for `[genesis, now)`
+ *  from `avail_geo.ts`'s `TIERS`, and reports:
+ *    - which cover slots are satisfied by present shards
+ *    - the first missing period (if any)
+ *    - `staleShardCount`: present shards NOT in the current min-cover
+ *      (usually old max-rung tiles that got superseded — GC candidates)
  *
- *  D1 column compatibility: pre-P3 the column is `cadence`; post-P3
- *  it's `shard_dur`. Probe schema once and substitute. */
+ *  D1 column compatibility: pre-P3 the column is `cadence`; post-P3 it's
+ *  `shard_dur`. Probe schema once and substitute. */
 export async function getPyramidsHealth(db: D1Database): Promise<PyramidsHealth> {
 	// Probe which column name the D1 schema uses (P3 transition).
 	let shardCol = 'shard_dur';
@@ -334,29 +357,22 @@ export async function getPyramidsHealth(db: D1Database): Promise<PyramidsHealth>
 	}
 
 	const PYRAMID = 'avail';
-	const { TIERS } = await import('./avail_geo');
+	const { TIERS, AVAIL_GENESIS } = await import('./avail_geo');
 	const largestPerTier: Record<string, string> = Object.fromEntries(
 		TIERS.map((t) => [t.name, t.shards[t.shards.length - 1]!])
 	);
 
-	// One query for all shards of this pyramid; one for watermarks.
-	type ShardRow = { tier: string; sd: string; n: number; earliest: number; latest: number };
-	type WmRow = { tier: string; sd: string; latest_period_end: number };
-	const shardSql = `SELECT tier, ${shardCol} AS sd, COUNT(*) AS n, ` +
-		`MIN(period_start) AS earliest, MAX(period_end) AS latest ` +
-		`FROM pyramid_shards WHERE pyramid = ? GROUP BY tier, ${shardCol}`;
-	const wmSql = `SELECT tier, ${shardCol} AS sd, latest_period_end ` +
-		`FROM pyramid_watermarks WHERE pyramid = ?`;
+	// All shard rows for this pyramid. ~5-10k rows for avail-v3 today; well
+	// within a single D1 query.
+	type ShardRow = { tier: string; sd: string; period_start: number };
+	const shardSql =
+		`SELECT tier, ${shardCol} AS sd, period_start ` +
+		`FROM pyramid_shards WHERE pyramid = ?`;
 
 	let shardRows: ShardRow[] = [];
-	let wmRows: WmRow[] = [];
 	try {
-		const [s, w] = await Promise.all([
-			db.prepare(shardSql).bind(PYRAMID).all<ShardRow>(),
-			db.prepare(wmSql).bind(PYRAMID).all<WmRow>(),
-		]);
+		const s = await db.prepare(shardSql).bind(PYRAMID).all<ShardRow>();
 		shardRows = s.results ?? [];
-		wmRows = w.results ?? [];
 	} catch {
 		// D1 unavailable — return empty.
 		return [];
@@ -366,33 +382,106 @@ export async function getPyramidsHealth(db: D1Database): Promise<PyramidsHealth>
 	const norm = (tier: string, sd: string): string =>
 		sd === '' ? (largestPerTier[tier] ?? sd) : sd;
 
-	const shardsByKey = new Map<string, ShardRow>();
-	for (const r of shardRows) shardsByKey.set(`${r.tier}@${norm(r.tier, r.sd)}`, r);
-	const wmByKey = new Map<string, WmRow>();
-	for (const r of wmRows) wmByKey.set(`${r.tier}@${norm(r.tier, r.sd)}`, r);
-
-	const isoMs = (ms: number | null): string | null =>
-		ms === null || ms === undefined ? null : new Date(ms).toISOString();
-
-	const tiers = TIERS.map((t) => ({
-		tier: t.name,
-		bin: String(t.bin),
-		shards: t.shards.map((sd) => {
-			const key = `${t.name}@${sd}`;
-			const s = shardsByKey.get(key);
-			const w = wmByKey.get(key);
-			return {
-				tier: t.name,
-				shardDur: String(sd),
-				shardCount: s ? s.n : 0,
-				earliestPeriodStart: s ? isoMs(s.earliest) : null,
-				latestPeriodEnd: s ? isoMs(s.latest) : null,
-				watermarkEnd: w ? isoMs(w.latest_period_end) : null,
-			};
-		}),
-	}));
+	// Index: `tier\x00shardDur\x00periodStartMs` → present.
+	const presentKey = (tier: string, sd: string, periodStartMs: number) =>
+		`${tier}\x00${sd}\x00${periodStartMs}`;
+	const present = new Set<string>();
+	const presentByTier: Record<string, number> = {};
+	for (const r of shardRows) {
+		const sd = norm(r.tier, r.sd);
+		present.add(presentKey(r.tier, sd, r.period_start));
+		presentByTier[r.tier] = (presentByTier[r.tier] ?? 0) + 1;
+	}
+
+	// Min-cover of [genesis, now] per tier via pyrmts. `listExpectedShards`
+	// returns max-rung tiles filling the closed-history region + dust rungs
+	// for the trailing partial-max window. We infer `role` from the shardDur
+	// (max iff === tier's largest rung).
+	const now = new Date();
+	// pyrmts's Pyramid requires more fields for full query use, but
+	// listExpectedShards only reads `.tiers` and `.keyTemplate`. Cast the
+	// stub to shut the compiler up.
+	const pyramid = {
+		tiers: TIERS,
+		keyTemplate: 'avail-v3/{tier}/{shard}/{period}.parquet',
+	} as unknown as Pyramid;
+	const expected = listExpectedShards(pyramid, { from: AVAIL_GENESIS, to: now });
+	const expectedByTier = new Map<string, typeof expected>();
+	for (const e of expected) {
+		const list = expectedByTier.get(e.tier) ?? [];
+		list.push(e);
+		expectedByTier.set(e.tier, list);
+	}
+
+	const tiers: PyramidTierCoverStatus[] = [];
+	let totalMissing = 0;
+	let totalStale = 0;
+
+	for (const t of TIERS) {
+		const maxRung = t.shards[t.shards.length - 1]!;
+		const maxSpan = parseDuration(maxRung);
+		const lastMaxBoundary = floorToSpan(now, maxSpan);
+		const cover = expectedByTier.get(t.name) ?? [];
+
+		// Aggregate by rung (preserving order of first appearance in cover).
+		const rungOrder: string[] = [];
+		const rungAgg: Record<string, { expected: number; present: number; role: 'max' | 'dust' }> = {};
+		let firstMissingPeriod: string | null = null;
+		let coverPresent = 0;
+
+		for (const slot of cover) {
+			const role: 'max' | 'dust' = slot.shardDur === maxRung ? 'max' : 'dust';
+			if (!(slot.shardDur in rungAgg)) {
+				rungOrder.push(slot.shardDur);
+				rungAgg[slot.shardDur] = { expected: 0, present: 0, role };
+			}
+			const agg = rungAgg[slot.shardDur]!;
+			agg.expected += 1;
+			const key = presentKey(t.name, slot.shardDur, slot.periodStart.getTime());
+			if (present.has(key)) {
+				agg.present += 1;
+				coverPresent += 1;
+			} else if (firstMissingPeriod === null) {
+				firstMissingPeriod = slot.periodStart.toISOString();
+			}
+		}
+
+		const rungs: PyramidCoverRung[] = rungOrder.map((sd) => ({
+			shardDur: sd,
+			role: rungAgg[sd]!.role,
+			expected: rungAgg[sd]!.expected,
+			present: rungAgg[sd]!.present,
+		}));
+		const totalExpected = cover.length;
+		const staleShardCount = Math.max(0, (presentByTier[t.name] ?? 0) - coverPresent);
+
+		totalMissing += (totalExpected - coverPresent);
+		totalStale += staleShardCount;
+
+		tiers.push({
+			tier: t.name,
+			bin: String(t.bin),
+			maxRung,
+			rungs,
+			totalExpected,
+			totalPresent: coverPresent,
+			complete: coverPresent === totalExpected,
+			firstMissingPeriod,
+			lastMaxBoundary: lastMaxBoundary.toISOString(),
+			dustAgeSec: Math.floor((now.getTime() - lastMaxBoundary.getTime()) / 1000),
+			staleShardCount,
+		});
+	}
 
-	return [{ name: PYRAMID, tiers }];
+	return [{
+		name: PYRAMID,
+		genesis: AVAIL_GENESIS.toISOString(),
+		now: now.toISOString(),
+		tiers,
+		totalMissing,
+		totalStale,
+		allComplete: totalMissing === 0,
+	}];
 }
 
 export async function getTripdataHealth(r2: HealthR2): Promise<TripdataHealth | null> {