@bongos/core 1.19.539 → 1.19.541

package/modules/hall-ui/public/style.css

@@ -1988,6 +1988,37 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
 .kit-chart__empty { font-size: 12px; color: var(--ink-faint); }
 .kit-chart__foot { font-size: 11.5px; color: var(--ink-faint); margin-top: 4px; }
 
+/* The contribution calendar — OTBKit.calendarGridHtml (task 1003572), the hall's
+   THIRD chart family. A year grid of small cells, banded by ship count 0..5. Theme-
+   aware by construction: every band is a color-mix off --accent and --surface-2, both
+   theme tokens, so light and dark read without a second palette and level 5 is the
+   full accent in either. The grid is wide, so .kit-cal__scroll holds it in its OWN
+   horizontal strip — the document never scrolls sideways (hall-ui/CLAUDE.md). */
+.kit-cal { display: flex; flex-direction: column; gap: 6px; --kit-cal-cell: 11px; }
+.kit-cal__scroll { overflow-x: auto; padding-bottom: 2px; }
+.kit-cal__grid {
+  display: grid;
+  grid-template-rows: repeat(7, var(--kit-cal-cell));
+  grid-auto-flow: column;
+  grid-auto-columns: var(--kit-cal-cell);
+  gap: 3px;
+  width: max-content; /* intrinsic width; the scroll strip, not the document, holds it */
+}
+.kit-cal__cell {
+  width: var(--kit-cal-cell); height: var(--kit-cal-cell);
+  border-radius: 2px;
+  background: var(--surface-2);
+}
+.kit-cal__cell[data-level="1"] { background: color-mix(in srgb, var(--accent) 25%, var(--surface-2)); }
+.kit-cal__cell[data-level="2"] { background: color-mix(in srgb, var(--accent) 45%, var(--surface-2)); }
+.kit-cal__cell[data-level="3"] { background: color-mix(in srgb, var(--accent) 65%, var(--surface-2)); }
+.kit-cal__cell[data-level="4"] { background: color-mix(in srgb, var(--accent) 82%, var(--surface-2)); }
+.kit-cal__cell[data-level="5"] { background: var(--accent); }
+.kit-cal__cell--void { background: transparent; }
+.kit-cal__key { display: flex; align-items: center; gap: 3px; font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-faint); }
+.kit-cal__key .kit-cal__cell { --kit-cal-cell: 10px; }
+.kit-cal__key-label { margin: 0 2px; }
+
 .kit-spark { width: 100%; height: 44px; display: block; }
 /* The stroke/fill here are the FALLBACK: sparklineHtml writes the caller's
    colour inline, because the Curve spends a different accent per chart. */

package/modules/ideas/blockers.js

@@ -9,15 +9,20 @@
 
 const { pool } = require('../../src/module-api');
 
+// Shared by listOpenBlockers + getBlocker so the two reads can never drift
+// (task 1002459 — getBlocker used to omit this column entirely, so a
+// link-then-verify against the detail route read as a false negative).
+const BLOCKING_TASK_IDS_SQL = `COALESCE(
+              (SELECT array_agg(tb.task_id ORDER BY tb.task_id)
+                 FROM task_blockers tb WHERE tb.blocker_id = b.id),
+              ARRAY[]::bigint[]
+            ) AS blocking_task_ids`;
+
 async function listOpenBlockers() {
   const { rows } = await pool.query(
     `SELECT b.id, b.title, b.body_md, b.status, b.created_at,
             b.source, b.source_ref,
-            COALESCE(
-              (SELECT array_agg(tb.task_id ORDER BY tb.task_id)
-                 FROM task_blockers tb WHERE tb.blocker_id = b.id),
-              ARRAY[]::bigint[]
-            ) AS blocking_task_ids
+            ${BLOCKING_TASK_IDS_SQL}
        FROM blockers b
       WHERE b.status = 'open'
       ORDER BY b.id`
@@ -27,9 +32,10 @@ async function listOpenBlockers() {
 
 async function getBlocker(id) {
   const { rows } = await pool.query(
-    `SELECT id, title, body_md, status, created_at, resolved_at, resolved_by, resolution_note,
-            source, source_ref
-       FROM blockers WHERE id = $1`,
+    `SELECT b.id, b.title, b.body_md, b.status, b.created_at, b.resolved_at, b.resolved_by,
+            b.resolution_note, b.source, b.source_ref,
+            ${BLOCKING_TASK_IDS_SQL}
+       FROM blockers b WHERE b.id = $1`,
     [id]
   );
   return rows[0] || null;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.539",
+  "version": "1.19.541",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.539",
+      "version": "1.19.541",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.539",
+  "version": "1.19.541",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/routes/me.js

@@ -45,6 +45,34 @@ const seams = require('../../module-seams');
 // `lifecycle` kernel PORT (lc()); the grade-TREND read (builderRollingAvgGrade)
 // stays core db (the sessions BFG also consumes it — kept on the doorway).
 const lc = () => seams.resolveOptional('lifecycle');
+
+// boundShipDaysToYear(rows, todayStr) — the last ~year of a builder's ship-day
+// counts, for the hall's contribution calendar (task 1003572). `rows` is
+// computeStreak's `ship_day_counts` ([{ local_date:'YYYY-MM-DD', count }]) ascending
+// in the builder's own timezone; `todayStr` is that same day. A calendar shows a
+// year, and /me is the hall's busiest boot read, so an unbounded array is the exact
+// over-fetch criterion legibility-sort-and-staleness names — the bound is the point.
+//
+// The cutoff is computed on the YYYY-MM-DD-as-UTC convention the streak math already
+// uses (Date.UTC on the parsed parts), never through the server's local clock, so it
+// cannot drift a day the way `new Date('2026-09-03')` would. 371 days = 53 whole
+// weeks, so the grid the calendar draws is always full-width with no partial column.
+const YMD_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function boundShipDaysToYear(rows, todayStr) {
+  if (!Array.isArray(rows) || rows.length === 0) return [];
+  const toOrd = (ymd) => {
+    const m = YMD_RE.exec(String(ymd || ''));
+    if (!m) return null;
+    return Math.floor(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) / 86400000);
+  };
+  const todayOrd = toOrd(todayStr);
+  if (todayOrd == null) return rows.slice(-371); // no today anchor → last 371 rows, still bounded
+  const cutoff = todayOrd - 370;
+  return rows.filter((r) => {
+    const o = toOrd(r && r.local_date);
+    return o != null && o >= cutoff && o <= todayOrd;
+  });
+}
 // The dev-box "has this builder ever connected a box?" signal, read through the
 // kernel seam instead of a direct `require('../boxes')` (a forbidden core→module
 // edge once dev-box moved to modules/dev-box/, ADR 0083 / BV1.R43). The dev-box
@@ -302,6 +330,15 @@ module.exports = function buildMeRouter() {
         started_on: streakInfo.current_started_on,
         timezone: streakInfo.timezone,
         today: streakInfo.today,
+        // The per-day ship counts computeStreak already produced and this block
+        // used to drop (task 1003572, criterion legibility-series-are-drawn): the
+        // hall's contribution calendar draws them. BOUNDED to roughly a year — a
+        // calendar shows a year, and an unbounded array would grow without limit on
+        // the busiest boot read the hall has. `ship_day_counts` is ascending in the
+        // builder's own timezone ({local_date:'YYYY-MM-DD', count:1..5}); the cutoff
+        // is computed on the same YYYY-MM-DD-as-UTC convention the streak math uses,
+        // never through the request's local clock.
+        ship_days: boundShipDaysToYear(streakInfo.ship_day_counts, streakInfo.today),
       },
       grades: {
         recent: recentGrades,
@@ -531,3 +568,8 @@ module.exports = function buildMeRouter() {
 
   return router;
 };
+
+// Exported for tests only: the "bounded to a year" + timezone-safe cutoff behind the
+// contribution calendar (task 1003572). The route mounts the router; this is the one
+// pure function inside it whose correctness is worth pinning without a DB.
+module.exports.boundShipDaysToYear = boundShipDaysToYear;

package/src/module-api.js

@@ -49,7 +49,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.539'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.541'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/blocker_detail_hydration.mjs

@@ -0,0 +1,128 @@
+// tests/blocker_detail_hydration.mjs
+//
+// task 1002459 — GET /blockers/:id was missing `blocking_task_ids`, the array
+// the list route (GET /blockers) already returns for the same row. A caller
+// doing the natural link-then-verify (link a task, then re-fetch the blocker
+// by id to confirm) read that as a false negative — the ids were never gone,
+// `getBlocker`'s SELECT just never asked for them.
+//
+// The fix hoists the array_agg fragment into one shared constant
+// (BLOCKING_TASK_IDS_SQL) so `listOpenBlockers` and `getBlocker` cannot drift
+// apart again the way they did here. This test pins that: both queries must
+// carry the identical fragment, and the detail route's SELECT must not add a
+// status filter the list route has (task_blockers rows persist after resolve,
+// so a resolved blocker's field reads as "tasks it WAS blocking" — a
+// deliberate widening, not a bug, per the task's decision note).
+//
+// DB-free: `modules/ideas/blockers.js` destructures `pool` off the doorway at
+// require time, so patching `pool.query` on that same object — BEFORE
+// requiring blockers.js — intercepts every query. No live Postgres needed.
+//
+// Run:  node tests/blocker_detail_hydration.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const api = require('../src/module-api.js');
+
+let queries = [];
+
+api.pool.query = async (sql, params = []) => {
+  queries.push({ sql: String(sql), params });
+  if (/FROM blockers b\s+WHERE b\.status = 'open'/.test(sql)) {
+    return {
+      rows: [
+        { id: '1000085', title: 'the open one', body_md: '', status: 'open',
+          created_at: new Date(), source: 'manual', source_ref: null,
+          blocking_task_ids: ['1001838', '1001839'] },
+      ],
+    };
+  }
+  if (/FROM blockers b WHERE b\.id = \$1/.test(sql)) {
+    const id = String(params[0]);
+    if (id === '1000085') {
+      return {
+        rows: [
+          { id: '1000085', title: 'the open one', body_md: '', status: 'open',
+            created_at: new Date(), resolved_at: null, resolved_by: null,
+            resolution_note: null, source: 'manual', source_ref: null,
+            blocking_task_ids: ['1001838', '1001839'] },
+        ],
+      };
+    }
+    if (id === '1000099') {
+      // A resolved blocker: task_blockers rows persist, so the field still
+      // reports the tasks it WAS blocking (see comment above).
+      return {
+        rows: [
+          { id: '1000099', title: 'the resolved one', body_md: '', status: 'resolved',
+            created_at: new Date(), resolved_at: new Date(), resolved_by: '41',
+            resolution_note: 'done', source: 'manual', source_ref: null,
+            blocking_task_ids: ['1002000'] },
+        ],
+      };
+    }
+    return { rows: [] };
+  }
+  throw new Error(`unexpected query: ${sql}`);
+};
+
+const blockers = require('../modules/ideas/blockers.js');
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  queries = [];
+  try {
+    await fn();
+    passed += 1;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed += 1;
+    console.log(`  FAIL  ${name}\n      ${err.message}`);
+  }
+}
+
+function blockingTaskIdsFragment(sql) {
+  const match = sql.match(/COALESCE\(\s*\(SELECT array_agg\(tb\.task_id[\s\S]*?blocking_task_ids/);
+  assert.ok(match, `query does not carry a blocking_task_ids projection:\n${sql}`);
+  return match[0].replace(/\s+/g, ' ').trim();
+}
+
+await test('listOpenBlockers and getBlocker project blocking_task_ids from the identical fragment', async () => {
+  await blockers.listOpenBlockers();
+  const listSql = queries[queries.length - 1].sql;
+
+  queries = [];
+  await blockers.getBlocker(1000085);
+  const detailSql = queries[queries.length - 1].sql;
+
+  assert.equal(blockingTaskIdsFragment(detailSql), blockingTaskIdsFragment(listSql));
+});
+
+await test('getBlocker returns blocking_task_ids on the row — the gap this task closes', async () => {
+  const row = await blockers.getBlocker(1000085);
+  assert.deepEqual(row.blocking_task_ids, ['1001838', '1001839']);
+});
+
+await test('getBlocker does not restrict by status — the list route is open-only, the detail route is not', async () => {
+  const detailSql = (await (async () => { await blockers.getBlocker(1000085); return queries[queries.length - 1].sql; })());
+  assert.ok(!/WHERE b\.status = 'open'/.test(detailSql), 'detail query must not gain the list route\'s open-only filter');
+});
+
+await test('a resolved blocker still reports the tasks it WAS blocking (task_blockers rows persist)', async () => {
+  const row = await blockers.getBlocker(1000099);
+  assert.equal(row.status, 'resolved');
+  assert.deepEqual(row.blocking_task_ids, ['1002000']);
+});
+
+await test('getBlocker still returns null for an id with no row', async () => {
+  const row = await blockers.getBlocker(999999);
+  assert.equal(row, null);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/hall_audit.mjs

@@ -256,7 +256,9 @@ test('the kit is the ONLY thing in the hall that draws a bar series', () => {
   const stamped = [];
   for (const f of fs.readdirSync(HALL)) {
     if (!/\.(html|js)$/.test(f) || f === OWNER) continue;
-    if (/class="kit-(?:bars|spark|plot)[\s"_-]/.test(read(f))) stamped.push(f);
+    // `cal` joins the family (task 1003572): the contribution calendar is stamped by
+    // OTBKit.calendarGridHtml, so a `kit-cal` class in any other file is a hand-roll.
+    if (/class="kit-(?:bars|spark|plot|cal)[\s"_-]/.test(read(f))) stamped.push(f);
   }
   assert.deepEqual(stamped, [],
     `${stamped.join(', ')} writes the kit's own chart classes by hand — call `
@@ -317,6 +319,7 @@ test('the three bar copies are gone, and their class families with them', () =>
   assert.match(read('hall-render.js'), /OTBKit\.barSeriesHtml\(/, 'the Curve\'s kinds draw through the kit');
   assert.match(read('watch.js'), /OTBKit\.barSeriesHtml\(/, 'Watch\'s trend draws through the kit');
   assert.match(read('profile-charts.js'), /OTBKit\.barSeriesHtml\(/, 'the craft mix draws through the kit');
+  assert.match(read('profile-charts.js'), /OTBKit\.calendarGridHtml\(/, 'the contribution calendar draws through the kit (task 1003572)');
   assert.match(read('hall-render.js'), /OTBKit\.sparklineHtml\(/, 'and the Curve\'s line does too');
 });
 

package/tests/hall_kit_charts.mjs

@@ -548,3 +548,78 @@ test('RUN: the timeline refuses to draw rather than drawing an empty axis', asyn
   assert.doesNotMatch(card.html, />C</, 'the unstarted version is not a bar');
   assert.match(card.html, /1 version with no start date is not shown/, 'the foot says so');
 });
+
+// ---- the contribution calendar (task 1003572) -------------------------------
+//
+// The hall's third chart family: a year grid, banded by count, read by per-cell
+// title + an aria summary. These pin the arithmetic (banding, the 5-cap), the
+// timezone trap the task names, and the empty-history contract.
+
+test('CAL: a day lands on the cell its own YYYY-MM-DD names, banded by count', () => {
+  const html = kit.calendarGridHtml([
+    { local_date: '2026-09-01', count: 2 },
+    { local_date: '2026-09-03', count: 5 },
+  ], { today: '2026-09-03', weeks: 6 });
+  assert.match(html, /2026-09-03 · 5 ships/);
+  assert.match(html, /2026-09-01 · 2 ships/);
+  assert.match(html, /data-level="5"/, 'a 5-ship day hits the top band');
+  assert.match(html, /data-level="2"/);
+  assert.match(html, /· no ships/, 'quiet days are titled too, not blank');
+});
+
+test('CAL: the band caps at 5 — the same anti-gaming cap streak.js applies', () => {
+  // count can only be 1..5 from the server, but the primitive must not emit a 6th
+  // band if a caller ever over-counts.
+  const html = kit.calendarGridHtml([{ local_date: '2026-09-03', count: 9 }], { today: '2026-09-03', weeks: 2 });
+  assert.match(html, /2026-09-03 · 9 ships/, 'the title reports the real number');
+  assert.match(html, /data-level="5"/, 'but the band is clamped to 5');
+  assert.doesNotMatch(html, /data-level="[6-9]"/);
+});
+
+test('CAL: the aria summary states the figure in words for a non-picture reader', () => {
+  const html = kit.calendarGridHtml([
+    { local_date: '2026-09-01', count: 2 },
+    { local_date: '2026-09-02', count: 1 },
+  ], { today: '2026-09-03' });
+  assert.match(html, /aria-label="Ships per day over the last year: 3 ships across 2 days\./);
+  assert.match(html, /role="img"/);
+});
+
+test('CAL: singular grammar — one ship, one day', () => {
+  const html = kit.calendarGridHtml([{ local_date: '2026-09-03', count: 1 }], { today: '2026-09-03' });
+  assert.match(html, /2026-09-03 · 1 ship"/, "no plural s on one ship");
+  assert.match(html, /1 ship across 1 day\./);
+});
+
+test('CAL: no timezone shift — the cell is fixed by the date string, not the runner clock', () => {
+  // The trap the task names: `new Date("2026-09-03")` is UTC-midnight and shifts a
+  // day west of Greenwich. The primitive uses Date.UTC on the parsed parts, so the
+  // title for a date is that date regardless of process.env.TZ.
+  const days = [{ local_date: '2026-01-01', count: 3 }];
+  const run = () => kit.calendarGridHtml(days, { today: '2026-01-07', weeks: 3 });
+  const saved = process.env.TZ;
+  try {
+    process.env.TZ = 'Pacific/Kiritimati'; // UTC+14, the worst case east
+    const a = run();
+    process.env.TZ = 'Pacific/Pago_Pago';  // UTC-11, the worst case west
+    const b = run();
+    assert.match(a, /2026-01-01 · 3 ships/);
+    assert.match(b, /2026-01-01 · 3 ships/);
+    // and the cell index is identical in both — no column/row drift.
+    assert.equal(a, b, 'the grid is byte-identical across extreme timezones');
+  } finally { process.env.TZ = saved; }
+});
+
+test('CAL: empty history draws nothing, so the caller shows its own empty state', () => {
+  assert.equal(kit.calendarGridHtml([], {}), '');
+  assert.equal(kit.calendarGridHtml(null, {}), '');
+  assert.equal(kit.calendarGridHtml([{ local_date: '2026-09-03', count: 0 }], {}), '',
+    'a zero-count day is not a ship — nothing to draw');
+  assert.equal(kit.calendarGridHtml([{ local_date: 'not-a-date', count: 2 }], {}), '',
+    'an unparseable date is dropped, not floored to the epoch');
+});
+
+test('CAL: the grid gets its own horizontal strip — it never widens the document', () => {
+  const html = kit.calendarGridHtml([{ local_date: '2026-09-03', count: 1 }], { today: '2026-09-03' });
+  assert.match(html, /kit-cal__scroll/, 'the wide grid scrolls inside its own strip');
+});

package/tests/hall_profile_world.mjs

@@ -122,7 +122,10 @@ test('profile-charts.js loads before profile.js, and profile.js hands it the pag
   const a = html.indexOf('/builders/profile-charts.js');
   const b = html.indexOf('/builders/profile.js');
   assert.ok(a > 0 && a < b, 'the charts script is in the page, ahead of profile.js');
-  assert.match(profileJs, /window\.OTBProfileCharts\.render\(\{ api, API, builderId: builder\.id, selfId, signedIn: selfId != null \}\)/);
+  // task 1003572 threads the viewer's own streak (for the contribution calendar) as a
+  // fifth field; the assertion checks the stable prefix rather than the exact tail.
+  assert.match(profileJs, /window\.OTBProfileCharts\.render\(\{ api, API, builderId: builder\.id, selfId, signedIn: selfId != null/);
+  assert.match(profileJs, /selfStreak: \(selfMe && selfMe\.streak\) \|\| null/, 'the own-streak is handed to the charts for the calendar');
   assert.match(html, /<section class="scroll" id="charts-scroll"[^>]*>[\s\S]*?<div class="pcharts" id="charts-grid">/, 'the charts section is a .pcharts grid');
 });
 

package/tests/me_ship_days_bound.mjs

@@ -0,0 +1,76 @@
+// tests/me_ship_days_bound.mjs — the year bound on /me's ship_days (task 1003572,
+// criterion legibility-series-are-drawn).
+//
+// The row array computeStreak produces is unbounded, and /me is the hall's busiest
+// boot read, so shipping the whole history is the exact over-fetch a sibling criterion
+// (legibility-sort-and-staleness) names. This pins the two properties that make the
+// field safe to add: it is BOUNDED to about a year, and the cutoff is TIMEZONE-SAFE —
+// computed on the YYYY-MM-DD-as-UTC convention, never the server's local clock.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { boundShipDaysToYear } = require('../src/bongos/routes/me.js');
+
+// A pure ordinal helper for building fixtures, matching the module's own convention.
+const ord = (y, m, d) => Math.floor(Date.UTC(y, m - 1, d) / 86400000);
+const ymd = (o) => { const dt = new Date(o * 86400000); return `${dt.getUTCFullYear()}-${String(dt.getUTCMonth() + 1).padStart(2, '0')}-${String(dt.getUTCDate()).padStart(2, '0')}`; };
+
+test('keeps roughly a year and drops what is older', () => {
+  const today = '2026-09-03';
+  const todayOrd = ord(2026, 9, 3);
+  const rows = [];
+  // one row every 10 days going back ~2 years
+  for (let o = todayOrd; o > todayOrd - 730; o -= 10) rows.unshift({ local_date: ymd(o), count: 1 });
+  const out = boundShipDaysToYear(rows, today);
+  assert.ok(out.length > 0);
+  // nothing older than the 371-day window survives
+  const cutoff = todayOrd - 370;
+  for (const r of out) {
+    const o = ord(...r.local_date.split('-').map(Number));
+    assert.ok(o >= cutoff && o <= todayOrd, `${r.local_date} is inside the year window`);
+  }
+  // and it is strictly smaller than the full 2-year input
+  assert.ok(out.length < rows.length, 'the old rows were dropped');
+});
+
+test('a future-dated row (clock skew) is not kept', () => {
+  const out = boundShipDaysToYear([
+    { local_date: '2026-09-03', count: 2 },
+    { local_date: '2027-01-01', count: 1 }, // after today
+  ], '2026-09-03');
+  assert.deepEqual(out.map((r) => r.local_date), ['2026-09-03']);
+});
+
+test('empty in, empty out — and a missing today anchor still bounds the array', () => {
+  assert.deepEqual(boundShipDaysToYear([], '2026-09-03'), []);
+  assert.deepEqual(boundShipDaysToYear(null, '2026-09-03'), []);
+  // No usable today → still bounded (last 371 rows), never the whole history.
+  const rows = Array.from({ length: 1000 }, (_, i) => ({ local_date: ymd(ord(2020, 1, 1) + i), count: 1 }));
+  const out = boundShipDaysToYear(rows, 'not-a-date');
+  assert.equal(out.length, 371, 'falls back to a bounded tail, not all 1000');
+});
+
+test('timezone-safe: the same rows bound to the same set under any TZ', () => {
+  // The point is invariance, not a specific boundary: `new Date("2025-01-01")` would be
+  // UTC-midnight and shift a day west of Greenwich, so a naive cutoff would keep a
+  // different set under UTC+14 vs UTC-11. Date.UTC on the parts does not.
+  const rows = [
+    { local_date: '2024-01-01', count: 1 }, // ~20 months old → always dropped
+    { local_date: '2025-06-15', count: 2 }, // ~15 months? within a year of 2026-09-03 → kept
+    { local_date: '2026-09-03', count: 1 }, // today → kept
+  ];
+  const saved = process.env.TZ;
+  const results = [];
+  try {
+    for (const tz of ['UTC', 'Pacific/Kiritimati', 'Pacific/Pago_Pago']) {
+      process.env.TZ = tz;
+      results.push(boundShipDaysToYear(rows, '2026-09-03').map((r) => r.local_date).join(','));
+    }
+  } finally { process.env.TZ = saved; }
+  assert.equal(results[0], results[1], 'UTC vs UTC+14 keep the same set');
+  assert.equal(results[1], results[2], 'UTC+14 vs UTC-11 keep the same set');
+  // and 2024 is out while today is in, whatever the TZ
+  assert.match(results[0], /2026-09-03/);
+  assert.doesNotMatch(results[0], /2024-01-01/);
+});