@bongos/core 1.19.539 → 1.19.540

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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.539",
+  "version": "1.19.540",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.539",
+      "version": "1.19.540",
       "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.540",
   "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.540'; // 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/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/);
+});