@remnic/core 9.66.2 → 9.66.3

package/src/activity/timeline/recap-id.ts

@@ -0,0 +1,10 @@
+/**
+ * Stable recap card-id order (issue #2051 leftover).
+ *
+ * localeCompare sort. Empty input → []. Does not mutate input. Drops empty strings.
+ */
+
+/** Return a new localeCompare-sorted id list. Empty strings are dropped. */
+export function sortRecapCardIds(ids: readonly string[]): string[] {
+  return ids.filter((id) => id !== "").sort((a, b) => a.localeCompare(b));
+}

package/src/activity/timeline/recap-markdown.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderRecapMarkdown } from "./recap-markdown.js";
+import type { TimelineCard } from "./types.js";
+
+const DATE = "2026-08-17";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Title",
+    summary: "Summary",
+    categoryId: "work",
+    confidence: 0.9,
+    startUtc: "2026-08-17T09:00:00.000Z",
+    endUtc: "2026-08-17T10:00:00.000Z",
+    dayKey: DATE,
+    timezone: "UTC",
+    machine: "machine-a",
+    evidenceIds: [1],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+test("empty cards print heading plus (empty)", () => {
+  assert.equal(
+    renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: [] }),
+    [`# Recap — ${DATE} (UTC)`, "", "(empty)", ""].join("\n"),
+  );
+});
+
+test("cards are sorted by id regardless of input order", () => {
+  const input = [card({ id: "card-c" }), card({ id: "card-a" }), card({ id: "card-b" })];
+  const first = renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: input });
+  const second = renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: input });
+  assert.equal(
+    first,
+    [`# Recap — ${DATE} (UTC)`, "", "- card-a", "- card-b", "- card-c", ""].join("\n"),
+  );
+  assert.deepEqual(
+    input.map((row) => row.id),
+    ["card-c", "card-a", "card-b"],
+  );
+  assert.equal(first, second);
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  assert.equal(
+    renderRecapMarkdown({ date: DATE, timezone: "America/Chicago", cards: [] }),
+    [`# Recap — ${DATE} (America/Chicago)`, "", "(empty)", ""].join("\n"),
+  );
+});

package/src/activity/timeline/recap-markdown.ts

@@ -0,0 +1,26 @@
+/**
+ * Deterministic Markdown recap from timeline cards (issue #2051 leftover).
+ *
+ * Pure: date + timezone + cards in, Markdown out. No LLM, no I/O, no
+ * persistence. Cards are sorted by id. Empty cards print (empty).
+ */
+import type { TimelineCard } from "./types.js";
+
+export interface RecapMarkdownOptions {
+  date: string;
+  timezone: string;
+  cards: readonly TimelineCard[];
+}
+
+function compareCardIds(a: TimelineCard, b: TimelineCard): number {
+  if (a.id < b.id) return -1;
+  if (a.id > b.id) return 1;
+  return 0;
+}
+
+/** Render a byte-stable Markdown recap for one local day. */
+export function renderRecapMarkdown(options: RecapMarkdownOptions): string {
+  const cards = [...options.cards].sort(compareCardIds);
+  const body = cards.length === 0 ? ["(empty)"] : cards.map((card) => `- ${card.id}`);
+  return [`# Recap — ${options.date} (${options.timezone})`, "", ...body, ""].join("\n");
+}

package/src/activity/timeline/recap-sort-key.test.ts

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { recapSortKey } from "./recap-sort-key.js";
+
+test("ok card id is the sort key", () => {
+  assert.equal(recapSortKey({ id: "card-1" }), "card-1");
+});
+
+test("missing id throws", () => {
+  assert.throws(() => recapSortKey({}), /missing recap card id/);
+  assert.throws(() => recapSortKey({ id: undefined }), /missing recap card id/);
+  assert.throws(() => recapSortKey({ id: null }), /missing recap card id/);
+});
+
+test("empty id throws", () => {
+  assert.throws(() => recapSortKey({ id: "" }), /empty recap card id/);
+});

package/src/activity/timeline/recap-sort-key.ts

@@ -0,0 +1,14 @@
+/**
+ * Recap card sort key (issue #2051 leftover).
+ *
+ * Returns card.id. Missing or empty id throws.
+ */
+export function recapSortKey(card: { id?: string | null }): string {
+  if (card.id == null) {
+    throw new Error("missing recap card id");
+  }
+  if (card.id === "") {
+    throw new Error("empty recap card id");
+  }
+  return card.id;
+}

package/src/activity/timeline/recap-tz.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeRecapTimezone } from "./recap-tz.js";
+
+test("accepts a trimmed IANA-shaped timezone", () => {
+  assert.deepEqual(normalizeRecapTimezone("America/Chicago"), {
+    ok: true,
+    timezone: "America/Chicago",
+  });
+});
+
+test("empty and whitespace-only values are missing_timezone", () => {
+  assert.deepEqual(normalizeRecapTimezone(""), { ok: false, error: "missing_timezone" });
+  assert.deepEqual(normalizeRecapTimezone("   "), { ok: false, error: "missing_timezone" });
+});
+
+test("rejects characters outside the bounded class", () => {
+  assert.deepEqual(normalizeRecapTimezone("America/Chicago!"), {
+    ok: false,
+    error: "invalid_timezone",
+  });
+  assert.deepEqual(normalizeRecapTimezone("America Chicago"), {
+    ok: false,
+    error: "invalid_timezone",
+  });
+  assert.deepEqual(normalizeRecapTimezone("A".repeat(65)), {
+    ok: false,
+    error: "invalid_timezone",
+  });
+});
+
+test("trims surrounding whitespace before validating", () => {
+  assert.deepEqual(normalizeRecapTimezone("  UTC  "), { ok: true, timezone: "UTC" });
+});

package/src/activity/timeline/recap-tz.ts

@@ -0,0 +1,19 @@
+/**
+ * Normalize a recap timezone string (issue #2051 leftover).
+ *
+ * Trim first. Empty → missing_timezone. Bounded charset only (no ReDoS).
+ */
+
+export type RecapTimezoneResult =
+  | { ok: true; timezone: string }
+  | { ok: false; error: "missing_timezone" | "invalid_timezone" };
+
+const RECAP_TIMEZONE = /^[A-Za-z0-9_+/-]{1,64}$/;
+
+/** Trim and accept an IANA-shaped timezone, or return a typed error. */
+export function normalizeRecapTimezone(value: string): RecapTimezoneResult {
+  const timezone = value.trim();
+  if (timezone.length === 0) return { ok: false, error: "missing_timezone" };
+  if (!RECAP_TIMEZONE.test(timezone)) return { ok: false, error: "invalid_timezone" };
+  return { ok: true, timezone };
+}

package/src/activity/timeline/week-count.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { countWeekDays } from "./week-count.js";
+
+test("empty list is 0", () => {
+  assert.equal(countWeekDays([]), 0);
+});
+
+test("counts unique YYYY-MM-DD dates", () => {
+  assert.equal(countWeekDays(["2026-08-17", "2026-08-18", "2026-08-17"]), 2);
+  assert.equal(countWeekDays(["2026-08-17", "2026-08-18", "2026-08-19"]), 3);
+});
+
+test("drops empty strings and does not mutate", () => {
+  const dates = ["2026-08-17", "", "2026-08-18", "", "2026-08-17"];
+  assert.equal(countWeekDays(dates), 2);
+  assert.deepEqual(dates, ["2026-08-17", "", "2026-08-18", "", "2026-08-17"]);
+});

package/src/activity/timeline/week-count.ts

@@ -0,0 +1,13 @@
+/**
+ * Week-day counter (issue #2052 leftover).
+ *
+ * Unique YYYY-MM-DD strings after dropping empty strings. Does not mutate input.
+ */
+
+export function countWeekDays(dates: readonly string[]): number {
+  const unique = new Set<string>();
+  for (const date of dates) {
+    if (date !== "") unique.add(date);
+  }
+  return unique.size;
+}

package/src/activity/timeline/week-days.test.ts

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { listWeekDates } from "./week-days.js";
+
+test("monday week is seven inclusive dates from start", () => {
+  assert.deepEqual(listWeekDates({ weekStartIso: "2026-07-13" }), [
+    "2026-07-13",
+    "2026-07-14",
+    "2026-07-15",
+    "2026-07-16",
+    "2026-07-17",
+    "2026-07-18",
+    "2026-07-19",
+  ]);
+});
+
+test("invalid date throws", () => {
+  assert.throws(() => listWeekDates({ weekStartIso: "2026-02-30" }), /YYYY-MM-DD/);
+  assert.throws(() => listWeekDates({ weekStartIso: "not-a-date" }), /YYYY-MM-DD/);
+});
+
+test("week always has length 7", () => {
+  assert.equal(listWeekDates({ weekStartIso: "2026-07-13" }).length, 7);
+  assert.equal(listWeekDates({ weekStartIso: "2026-01-28" }).length, 7);
+});

package/src/activity/timeline/week-days.ts

@@ -0,0 +1,23 @@
+/**
+ * Inclusive 7-day week from a YYYY-MM-DD start (issue #2052).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+export interface WeekDaysInput {
+  weekStartIso: string;
+}
+
+/** Parse `weekStartIso` as YYYY-MM-DD. Return `[start, start+6]`. */
+export function listWeekDates({ weekStartIso }: WeekDaysInput): string[] {
+  if (!isValidActivityDate(weekStartIso)) {
+    throw new RangeError(`Invalid week start "${weekStartIso}"; expected YYYY-MM-DD.`);
+  }
+  const start = new Date(`${weekStartIso}T00:00:00Z`);
+  const dates: string[] = [];
+  for (let offset = 0; offset < 7; offset++) {
+    const day = new Date(start);
+    day.setUTCDate(start.getUTCDate() + offset);
+    dates.push(day.toISOString().slice(0, 10));
+  }
+  return dates;
+}

package/src/activity/timeline/week-export.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { exportDeterministicWeek } from "./week-export.js";
+
+const WEEK_START = "2026-07-13";
+
+test("empty days export weekStart and timezone with an empty day list", () => {
+  const week = exportDeterministicWeek({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: [],
+  });
+  assert.deepEqual(week, { weekStart: WEEK_START, timezone: "UTC", days: [] });
+  assert.equal(
+    JSON.stringify(week),
+    `{"weekStart":"${WEEK_START}","timezone":"UTC","days":[]}`,
+  );
+});
+
+test("days are sorted by date regardless of input order", () => {
+  const week = exportDeterministicWeek({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: [{ date: "2026-07-15" }, { date: "2026-07-13" }, { date: "2026-07-14" }],
+  });
+  assert.deepEqual(
+    week.days.map((day) => day.date),
+    ["2026-07-13", "2026-07-14", "2026-07-15"],
+  );
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  const week = exportDeterministicWeek({
+    weekStart: WEEK_START,
+    timezone: "America/Chicago",
+    days: [],
+  });
+  assert.equal(week.timezone, "America/Chicago");
+});
+
+test("input days are not mutated and reruns are stable", () => {
+  const input = [{ date: "2026-07-15" }, { date: "2026-07-13" }];
+  const first = exportDeterministicWeek({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  const second = exportDeterministicWeek({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  assert.deepEqual(
+    input.map((day) => day.date),
+    ["2026-07-15", "2026-07-13"],
+  );
+  assert.equal(JSON.stringify(first), JSON.stringify(second));
+});

package/src/activity/timeline/week-export.ts

@@ -0,0 +1,44 @@
+/**
+ * Deterministic machine-readable week export from daily totals (issue #2052).
+ *
+ * Pure: weekStart + timezone + days in, stable JSON out. No LLM, no I/O, no
+ * persistence. Same days always serialize to the same bytes, regardless of
+ * input array order: days are sorted by date before serialization.
+ */
+
+export interface DeterministicWeekDay {
+  date: string;
+}
+
+export interface DeterministicWeekOptions {
+  weekStart: string;
+  timezone: string;
+  days: readonly DeterministicWeekDay[];
+}
+
+export interface DeterministicWeek {
+  weekStart: string;
+  timezone: string;
+  days: DeterministicWeekDay[];
+}
+
+function compareDates(a: DeterministicWeekDay, b: DeterministicWeekDay): number {
+  if (a.date < b.date) return -1;
+  if (a.date > b.date) return 1;
+  return 0;
+}
+
+/**
+ * Build the byte-stable JSON week document.
+ * Callers may `JSON.stringify` the returned object; construction order
+ * (weekStart, timezone, days) is fixed, so serialization is deterministic.
+ */
+export function exportDeterministicWeek(
+  options: DeterministicWeekOptions,
+): DeterministicWeek {
+  return {
+    weekStart: options.weekStart,
+    timezone: options.timezone,
+    days: [...options.days].sort(compareDates),
+  };
+}

package/src/activity/timeline/week-iso.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseIsoDate } from "./week-iso.js";
+
+test("accepts a trimmed YYYY-MM-DD date", () => {
+  assert.deepEqual(parseIsoDate("2026-08-19"), { ok: true, date: "2026-08-19" });
+  assert.deepEqual(parseIsoDate("  2026-08-19  "), { ok: true, date: "2026-08-19" });
+});
+
+test("empty and whitespace-only values are missing_date", () => {
+  assert.deepEqual(parseIsoDate(""), { ok: false, error: "missing_date" });
+  assert.deepEqual(parseIsoDate("   "), { ok: false, error: "missing_date" });
+});
+
+test("rejects strings that are not YYYY-MM-DD", () => {
+  assert.deepEqual(parseIsoDate("20260819"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseIsoDate("2026-8-19"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseIsoDate("2026-08-19T00:00:00Z"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseIsoDate("not-a-date"), { ok: false, error: "invalid_date" });
+});
+
+test("rejects impossible calendar days", () => {
+  assert.deepEqual(parseIsoDate("2026-02-30"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseIsoDate("2026-13-01"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseIsoDate("2026-00-10"), { ok: false, error: "invalid_date" });
+  // Real leap day still passes the round-trip.
+  assert.deepEqual(parseIsoDate("2024-02-29"), { ok: true, date: "2024-02-29" });
+});

package/src/activity/timeline/week-iso.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse a YYYY-MM-DD week date (issue #2052 leftover).
+ *
+ * Trim first. Empty → missing_date. Real YYYY-MM-DD calendar days only
+ * (no ReDoS, no impossible dates like 2026-02-30).
+ */
+
+import { isValidActivityDate } from "../digest.js";
+
+export type IsoDateResult =
+  | { ok: true; date: string }
+  | { ok: false; error: "missing_date" | "invalid_date" };
+
+/** Trim and accept a real YYYY-MM-DD calendar day, or return a typed error. */
+export function parseIsoDate(value: string): IsoDateResult {
+  const date = value.trim();
+  if (date.length === 0) return { ok: false, error: "missing_date" };
+  if (!isValidActivityDate(date)) return { ok: false, error: "invalid_date" };
+  return { ok: true, date };
+}

package/src/activity/timeline/week-monday.test.ts

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isMondayIso } from "./week-monday.js";
+
+test("monday UTC is true", () => {
+  assert.equal(isMondayIso("2026-07-13"), true);
+});
+
+test("tuesday UTC is false", () => {
+  assert.equal(isMondayIso("2026-07-14"), false);
+});
+
+test("invalid date throws", () => {
+  assert.throws(() => isMondayIso("2026-02-30"), /YYYY-MM-DD/);
+  assert.throws(() => isMondayIso("not-a-date"), /YYYY-MM-DD/);
+});

package/src/activity/timeline/week-monday.ts

@@ -0,0 +1,12 @@
+/**
+ * UTC Monday predicate for a YYYY-MM-DD date (issue #2052).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+/** Parse `dateIso` as YYYY-MM-DD. Monday UTC → true. */
+export function isMondayIso(dateIso: string): boolean {
+  if (!isValidActivityDate(dateIso)) {
+    throw new RangeError(`Invalid date "${dateIso}"; expected YYYY-MM-DD.`);
+  }
+  return new Date(`${dateIso}T00:00:00Z`).getUTCDay() === 1;
+}

package/src/activity/timeline/week-range.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { weekRange } from "./week-range.js";
+
+test("monday week is [start, start+7)", () => {
+  assert.deepEqual(weekRange({ weekStartIso: "2026-07-13" }), {
+    start: "2026-07-13",
+    endExclusive: "2026-07-20",
+  });
+});
+
+test("invalid date throws", () => {
+  assert.throws(() => weekRange({ weekStartIso: "2026-02-30" }), /YYYY-MM-DD/);
+  assert.throws(() => weekRange({ weekStartIso: "not-a-date" }), /YYYY-MM-DD/);
+});
+
+test("exclusive end is the next week start", () => {
+  const first = weekRange({ weekStartIso: "2026-07-13" });
+  const next = weekRange({ weekStartIso: first.endExclusive });
+  assert.equal(next.start, first.endExclusive);
+  assert.equal(next.endExclusive, "2026-07-27");
+});

package/src/activity/timeline/week-range.ts

@@ -0,0 +1,26 @@
+/**
+ * Half-open week range from a YYYY-MM-DD start (issue #2052).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+export interface WeekRangeInput {
+  weekStartIso: string;
+}
+
+export interface WeekRange {
+  start: string;
+  endExclusive: string;
+}
+
+/** Parse `weekStartIso` as YYYY-MM-DD. Return `[start, start+7)`. */
+export function weekRange({ weekStartIso }: WeekRangeInput): WeekRange {
+  if (!isValidActivityDate(weekStartIso)) {
+    throw new RangeError(`Invalid week start "${weekStartIso}"; expected YYYY-MM-DD.`);
+  }
+  const parsed = new Date(`${weekStartIso}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() + 7);
+  return {
+    start: weekStartIso,
+    endExclusive: parsed.toISOString().slice(0, 10),
+  };
+}

package/src/activity/timeline/week-snapshot.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderWeekSnapshot } from "./week-snapshot.js";
+
+const WEEK_START = "2026-07-13";
+
+test("empty days print heading + (empty)", () => {
+  assert.equal(
+    renderWeekSnapshot({
+      weekStart: WEEK_START,
+      timezone: "UTC",
+      days: [],
+    }),
+    [
+      "# Week snapshot",
+      "",
+      `- weekStart: ${WEEK_START}`,
+      "- timezone: UTC",
+      "",
+      "## Days",
+      "(empty)",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("days are sorted by date regardless of input order", () => {
+  const markdown = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: [{ date: "2026-07-15" }, { date: "2026-07-13" }, { date: "2026-07-14" }],
+  });
+  const headings = [...markdown.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
+  assert.deepEqual(headings, ["2026-07-13", "2026-07-14", "2026-07-15"]);
+  assert.match(markdown, /## 2026-07-13\n\(empty\)/);
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  const markdown = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "America/Chicago",
+    days: [],
+  });
+  assert.match(markdown, /^- timezone: America\/Chicago$/m);
+  assert.doesNotMatch(markdown, /America\/Chicago\/|UTC/);
+});
+
+test("input days are not mutated and reruns are stable", () => {
+  const input = [{ date: "2026-07-15" }, { date: "2026-07-13" }];
+  const first = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  const second = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  assert.deepEqual(
+    input.map((day) => day.date),
+    ["2026-07-15", "2026-07-13"],
+  );
+  assert.equal(first, second);
+});

package/src/activity/timeline/week-snapshot.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic markdown week snapshot from daily totals (issue #2052 leftover).
+ *
+ * Pure: weekStart + timezone + days in, stable markdown out. No LLM, no I/O, no
+ * persistence. Days are sorted by date. Empty days print heading + (empty).
+ */
+
+export interface WeekSnapshotDay {
+  date: string;
+}
+
+export interface WeekSnapshotOptions {
+  weekStart: string;
+  timezone: string;
+  days: readonly WeekSnapshotDay[];
+}
+
+function compareDates(a: WeekSnapshotDay, b: WeekSnapshotDay): number {
+  if (a.date < b.date) return -1;
+  if (a.date > b.date) return 1;
+  return 0;
+}
+
+/** Render a byte-stable Markdown week snapshot. */
+export function renderWeekSnapshot(options: WeekSnapshotOptions): string {
+  const days = [...options.days].sort(compareDates);
+  const body =
+    days.length === 0
+      ? ["## Days", "(empty)"]
+      : days.flatMap((day) => [`## ${day.date}`, "(empty)", ""]);
+  return [
+    "# Week snapshot",
+    "",
+    `- weekStart: ${options.weekStart}`,
+    `- timezone: ${options.timezone}`,
+    "",
+    ...body,
+    "",
+  ].join("\n");
+}

package/src/activity/timeline/week-sunday.test.ts

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isSundayIso } from "./week-sunday.js";
+
+test("sunday UTC is true", () => {
+  assert.equal(isSundayIso("2026-07-12"), true);
+});
+
+test("monday UTC is false", () => {
+  assert.equal(isSundayIso("2026-07-13"), false);
+});
+
+test("invalid date throws", () => {
+  assert.throws(() => isSundayIso("2026-02-30"), /YYYY-MM-DD/);
+  assert.throws(() => isSundayIso("not-a-date"), /YYYY-MM-DD/);
+});

package/src/activity/timeline/week-sunday.ts

@@ -0,0 +1,12 @@
+/**
+ * UTC Sunday predicate for a YYYY-MM-DD date (issue #2052).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+/** Parse `dateIso` as YYYY-MM-DD. Sunday UTC → true. */
+export function isSundayIso(dateIso: string): boolean {
+  if (!isValidActivityDate(dateIso)) {
+    throw new RangeError(`Invalid date "${dateIso}"; expected YYYY-MM-DD.`);
+  }
+  return new Date(`${dateIso}T00:00:00Z`).getUTCDay() === 0;
+}