@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/calendar/rrule.js

@@ -0,0 +1,261 @@
+/**
+ * rrule.ts — a pure RRULE reader for an honest, deliberately-bounded subset.
+ *
+ * The honesty rule (see the decision record): an event's recurrence is either
+ * FULLY and correctly expanded, or NOT expanded at all with an explicit reason.
+ * We never emit occurrences from a rule we do not completely honor — a half-honored
+ * BYMONTHDAY would put events on wrong dates, which is worse than not expanding.
+ *
+ * Fully supported (expanded to real occurrences):
+ *  - FREQ = DAILY | WEEKLY | MONTHLY | YEARLY
+ *  - INTERVAL (default 1)
+ *  - COUNT  (occurrence cap)
+ *  - UNTIL  (inclusive end bound; DATE or date-time, 'Z' or floating)
+ *  - BYDAY  — ONLY for FREQ=WEEKLY with INTERVAL=1 and weekday-only tokens
+ *             (MO,TU,WE,TH,FR,SA,SU with no leading ordinal). Under those
+ *             conditions WKST does not change the matched set, so it is ignored
+ *             safely. Any BYDAY outside that condition is treated as unsupported.
+ *
+ * Everything else present in the RRULE (BYMONTHDAY, BYMONTH, BYSETPOS, BYHOUR,
+ * BYWEEKNO, BYYEARDAY, ordinal BYDAY, BYDAY on non-weekly, INTERVAL>1 with BYDAY,
+ * or an unknown FREQ) marks the rule `unsupported` and names the offending part.
+ *
+ * PURE: no fs, no network, no process globals.
+ */
+const WEEKDAY_TOKENS = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'];
+const KNOWN_FREQ = new Set(['DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY']);
+/** Parts we fully honor; anything else present makes the rule unsupported. */
+const SUPPORTED_PARTS = new Set(['FREQ', 'INTERVAL', 'COUNT', 'UNTIL', 'WKST', 'BYDAY']);
+function parseRRule(rule) {
+    const map = new Map();
+    for (const seg of rule.split(';')) {
+        const eq = seg.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = seg.slice(0, eq).trim().toUpperCase();
+        const v = seg.slice(eq + 1).trim();
+        if (k !== '')
+            map.set(k, v);
+    }
+    return { map };
+}
+/**
+ * Classify a raw RRULE into an honest RecurrenceInfo. Called by the parser at read
+ * time so the event carries its expansion verdict before any window is known.
+ */
+export function describeRecurrence(rule) {
+    const { map } = parseRRule(rule);
+    const freq = (map.get('FREQ') ?? '').toUpperCase();
+    if (!KNOWN_FREQ.has(freq)) {
+        return { rule, expansion: 'unsupported', unsupportedReason: `RRULE FREQ '${freq || '(missing)'}' is not expanded by this build` };
+    }
+    for (const part of map.keys()) {
+        if (!SUPPORTED_PARTS.has(part)) {
+            return { rule, expansion: 'unsupported', unsupportedReason: `RRULE part ${part} is not expanded by this build` };
+        }
+    }
+    if (map.has('BYDAY')) {
+        const byDayVerdict = classifyByDay(freq, map);
+        if (byDayVerdict)
+            return { rule, expansion: 'unsupported', unsupportedReason: byDayVerdict };
+    }
+    return { rule, expansion: 'full' };
+}
+/** Return an unsupported-reason string if this BYDAY is outside the honored subset, else undefined. */
+function classifyByDay(freq, map) {
+    if (freq !== 'WEEKLY') {
+        return `RRULE BYDAY on FREQ=${freq} is not expanded by this build (only weekly BYDAY is supported)`;
+    }
+    const interval = parseInterval(map);
+    if (interval !== 1) {
+        return 'RRULE BYDAY with INTERVAL>1 is not expanded by this build (week-boundary/WKST handling required)';
+    }
+    const tokens = (map.get('BYDAY') ?? '').split(',').map((t) => t.trim().toUpperCase());
+    for (const tok of tokens) {
+        if (!WEEKDAY_TOKENS.includes(tok)) {
+            return `RRULE BYDAY token '${tok}' with an ordinal is not expanded by this build`;
+        }
+    }
+    return undefined;
+}
+function parseInterval(map) {
+    const raw = map.get('INTERVAL');
+    if (!raw)
+        return 1;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 1;
+}
+/** Parse an UNTIL value ('YYYYMMDD' or 'YYYYMMDDThhmmss[Z]') to a 'YYYY-MM-DD' date string. */
+function parseUntilDate(raw) {
+    const m = /^(\d{4})(\d{2})(\d{2})/.exec(raw.trim());
+    if (!m)
+        return undefined;
+    return `${m[1]}-${m[2]}-${m[3]}`;
+}
+/** Extract 'YYYY-MM-DD' from an EventDateTime value. */
+function datePart(value) {
+    return value.slice(0, 10);
+}
+/** Hard ceiling so a COUNT-less UNTIL-less rule cannot run away. */
+const MAX_OCCURRENCES = 1000;
+function toUtcDate(ymd) {
+    const [y, m, d] = ymd.split('-').map((s) => Number.parseInt(s, 10));
+    return Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1);
+}
+function fromUtcDate(ms) {
+    const d = new Date(ms);
+    const y = d.getUTCFullYear().toString().padStart(4, '0');
+    const m = (d.getUTCMonth() + 1).toString().padStart(2, '0');
+    const day = d.getUTCDate().toString().padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+const DAY_MS = 86_400_000;
+/** Build an occurrence start string that mirrors the seed's kind/zone. */
+function occurrenceStart(event, ymd) {
+    const s = event.start;
+    if (s.kind === 'date')
+        return ymd;
+    const time = s.value.slice(10); // 'THH:mm:ss' or 'THH:mm:ssZ'
+    return `${ymd}${time}`;
+}
+/**
+ * Expand a (possibly recurring) event into concrete occurrences inside [window.from,
+ * window.to] inclusive. A non-recurring event yields at most its single seed. An
+ * event whose recurrence is `unsupported` yields ONLY its seed (if in-window),
+ * flagged `isSeed`, never a fabricated series — the caller reads
+ * `event.recurrence.expansion` to label it "recurrence not fully expanded".
+ */
+export function expandEvent(event, window) {
+    const seedYmd = datePart(event.start.value);
+    const fromMs = toUtcDate(window.from);
+    const toMs = toUtcDate(window.to);
+    const seedMs = toUtcDate(seedYmd);
+    const inWindow = (ms) => ms >= fromMs && ms <= toMs;
+    const seedOccurrence = () => inWindow(seedMs) ? [{ event, start: occurrenceStart(event, seedYmd), isSeed: true }] : [];
+    if (!event.recurrence || event.recurrence.expansion !== 'full') {
+        return seedOccurrence();
+    }
+    const { map } = parseRRule(event.recurrence.rule);
+    const freq = (map.get('FREQ') ?? '').toUpperCase();
+    const interval = parseInterval(map);
+    const count = map.has('COUNT') ? Number.parseInt(map.get('COUNT') ?? '', 10) : undefined;
+    const untilYmd = map.has('UNTIL') ? parseUntilDate(map.get('UNTIL') ?? '') : undefined;
+    const untilMs = untilYmd ? toUtcDate(untilYmd) : undefined;
+    const byDay = map.has('BYDAY')
+        ? new Set((map.get('BYDAY') ?? '').split(',').map((t) => WEEKDAY_TOKENS.indexOf(t.trim().toUpperCase())))
+        : undefined;
+    const out = [];
+    let emitted = 0; // series position (counts every occurrence, in or out of window)
+    // `series` yields candidate UTC-midnight ms values in ascending series order.
+    // Weekly BYDAY walks day-by-day emitting matching weekdays; every other supported
+    // FREQ steps period-by-period from the seed. Both share one COUNT/UNTIL/window filter.
+    const emit = (ms) => {
+        // Return false to STOP the whole series (COUNT reached, past UNTIL, past window end).
+        if (count !== undefined && emitted >= count)
+            return false;
+        if (untilMs !== undefined && ms > untilMs)
+            return false;
+        if (ms > toMs)
+            return false;
+        emitted += 1;
+        if (ms >= fromMs) {
+            const ymd = fromUtcDate(ms);
+            out.push({ event, start: occurrenceStart(event, ymd), isSeed: ms === seedMs });
+        }
+        return true;
+    };
+    if (freq === 'WEEKLY' && byDay) {
+        let cursor = seedMs;
+        for (let i = 0; i < MAX_OCCURRENCES * 8; i++) {
+            if (byDay.has(new Date(cursor).getUTCDay())) {
+                if (!emit(cursor))
+                    break;
+            }
+            else if ((untilMs !== undefined && cursor > untilMs) || cursor > toMs) {
+                break; // no more matches possible past UNTIL / window end
+            }
+            cursor += DAY_MS;
+            if (cursor - seedMs > DAY_MS * 366 * 10)
+                break; // 10-year hard ceiling
+        }
+        return out;
+    }
+    if (freq === 'MONTHLY' || freq === 'YEARLY') {
+        stepMonthlyOrYearly(freq, interval, seedMs, toMs, untilMs, emit);
+        return out;
+    }
+    const step = freqStepper(freq, interval);
+    let cursor = seedMs;
+    for (let i = 0; i < MAX_OCCURRENCES; i++) {
+        if (!emit(cursor))
+            break;
+        cursor = step(cursor);
+    }
+    return out;
+}
+/** A stepper that advances a UTC-midnight ms cursor by one FREQ*INTERVAL period. DAILY/WEEKLY
+ *  only — MONTHLY/YEARLY need the anchor-day-preserving/skip-invalid logic in
+ *  stepMonthlyOrYearly below, since naive Date.UTC(y, m+1, day) arithmetic normalizes an
+ *  out-of-range day (e.g. day 31 in a 30-day month) into the NEXT month, permanently
+ *  shifting the rest of the series (the bug this file used to have). */
+function freqStepper(freq, interval) {
+    switch (freq) {
+        case 'DAILY':
+            return (ms) => ms + DAY_MS * interval;
+        case 'WEEKLY':
+            return (ms) => ms + DAY_MS * 7 * interval;
+        default:
+            return (ms) => ms + DAY_MS;
+    }
+}
+/**
+ * MONTHLY/YEARLY stepping, RFC 5545-correct: every candidate is measured from the
+ * ORIGINAL anchor day-of-month (`seedDay`), never from a previously normalized/drifted
+ * cursor. A candidate (year, month, seedDay) that is not a real calendar date — Feb 31,
+ * Feb 29 in a non-leap year, Apr 31, etc. — does not exist and is SKIPPED entirely: it is
+ * never passed to `emit`, so it never consumes COUNT and never appears in the output.
+ *
+ * Citation (RFC 5545 §3.3.10, "Recurrence Rule"): "Recurrence rules may generate
+ * recurrence instances with an invalid date (e.g., February 30) or nonexistent local time
+ * ... Such recurrence instances MUST be ignored and MUST NOT count towards the recurrence
+ * count specified by the COUNT rule part." This function and its COUNT bookkeeping (via
+ * the caller's `emit`) implement that rule directly: e.g. FREQ=MONTHLY anchored on the
+ * 31st walks Jan 31 -> Mar 31 -> May 31 -> ... (Feb/Apr/Jun skipped, uncounted); FREQ=YEARLY
+ * anchored on Feb 29 walks leap year -> leap year only.
+ */
+function stepMonthlyOrYearly(freq, interval, seedMs, toMs, untilMs, emit) {
+    const seed = new Date(seedMs);
+    const seedYear = seed.getUTCFullYear();
+    const seedMonth = seed.getUTCMonth();
+    const seedDay = seed.getUTCDate();
+    // Generous candidate ceiling (not an occurrence ceiling — MAX_OCCURRENCES already
+    // bounds emitted occurrences via `emit`/COUNT): covers the worst case of a monthly
+    // anchor that only lands ~7 times a year (a 31st) needing many more candidate
+    // months than emitted occurrences, and a yearly Feb-29 anchor needing up to 4x the
+    // candidate years.
+    const maxCandidates = freq === 'MONTHLY' ? MAX_OCCURRENCES * 12 : MAX_OCCURRENCES * 4;
+    for (let k = 0; k < maxCandidates; k++) {
+        const year = freq === 'MONTHLY'
+            ? Math.floor((seedYear * 12 + seedMonth + k * interval) / 12)
+            : seedYear + k * interval;
+        const month = freq === 'MONTHLY'
+            ? (((seedYear * 12 + seedMonth + k * interval) % 12) + 12) % 12
+            : seedMonth;
+        // Bail out once even the FIRST of this candidate month is past every hard stop —
+        // further k only move further forward, so nothing later can help either. This
+        // check runs before the validity check so a run of skipped (invalid) candidates
+        // near the end of the window does not burn through maxCandidates.
+        const monthStartMs = Date.UTC(year, month, 1);
+        if (monthStartMs > toMs && (untilMs === undefined || monthStartMs > untilMs))
+            return;
+        const candidateMs = Date.UTC(year, month, seedDay);
+        const candidate = new Date(candidateMs);
+        const isRealDate = candidate.getUTCFullYear() === year
+            && candidate.getUTCMonth() === month
+            && candidate.getUTCDate() === seedDay;
+        if (!isRealDate)
+            continue; // invalid calendar date — skipped, does not consume COUNT
+        if (!emit(candidateMs))
+            return;
+    }
+}

package/dist/platform/calendar/subscription-store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * subscription-store.ts — named external-calendar feed subscriptions with honest,
+ * per-subscription status. The engine that agent-side `/calendar subscribe` and the
+ * connect wizard drive.
+ *
+ * Reaches the network ONLY through an injected `FeedFetcher`, and reads time ONLY
+ * through an injected `Clock`. That is the whole IO boundary: tests supply fake
+ * feeds and a fake clock, so no test ever touches a real URL, and refresh/staleness
+ * timing is deterministic. Persistence is the CALLER's job (the agent stores the
+ * feed URL via its secret manager and the rest of the metadata in its config);
+ * `snapshot()` / `restore()` move that metadata across restarts, events re-fetched.
+ *
+ * UX shape (per Mike's least-friction rule): `add({ url })` is paste-URL-and-done —
+ * it validates by fetching, auto-derives the subscription name from the feed's
+ * X-WR-CALNAME (falling back to the URL host) when the caller gives no name, and
+ * applies a sensible default refresh interval with no mandatory knobs. Every status
+ * it reports is honest: stale carries its age, unreachable/parse-error carry the
+ * stage and detail.
+ *
+ * PURE of ambient IO — no direct fs/network/process; all IO is injected.
+ */
+import type { CalendarEvent, CalendarSubscription, Clock, FeedFetcher, RefreshReport, SubscriptionSnapshot } from './types.js';
+/** Sensible refresh cadence for a read-only feed that rarely changes minute-to-minute. */
+export declare const DEFAULT_REFRESH_INTERVAL_MS: number;
+/** Never hammer a feed faster than this, even if a caller asks. */
+export declare const MIN_REFRESH_INTERVAL_MS: number;
+/** A feed refreshed less often than this is capped up to here. */
+export declare const MAX_REFRESH_INTERVAL_MS: number;
+export interface SubscriptionStoreOptions {
+    readonly fetcher: FeedFetcher;
+    readonly clock?: Clock;
+    readonly defaultRefreshIntervalMs?: number;
+}
+export interface AddSubscriptionInput {
+    readonly url: string;
+    /** Optional; when omitted, derived from the feed's X-WR-CALNAME or the URL host. */
+    readonly name?: string;
+    readonly refreshIntervalMs?: number;
+}
+/** The outcome of validate-by-fetch — what the wizard shows before saving. */
+export type ValidationResult = {
+    readonly ok: true;
+    readonly calendarName?: string;
+    readonly eventCount: number;
+    readonly derivedName: string;
+} | {
+    readonly ok: false;
+    /** Which stage failed, so failure wording can name it honestly. */
+    readonly stage: 'fetch' | 'parse';
+    readonly detail: string;
+};
+export type AddResult = {
+    readonly ok: true;
+    readonly subscription: CalendarSubscription;
+    readonly report: RefreshReport;
+} | {
+    readonly ok: false;
+    readonly stage: 'fetch' | 'parse' | 'duplicate';
+    readonly detail: string;
+};
+/**
+ * Mask a feed URL for display. Google/Outlook "secret address" URLs grant read
+ * access, so a subscription's URL is secrets-adjacent — surfaces should show this,
+ * never the raw URL. Keeps the scheme+host and the last few chars, masks the middle.
+ */
+export declare function maskFeedUrl(url: string): string;
+export declare class SubscriptionStore {
+    private readonly fetcher;
+    private readonly clock;
+    private readonly defaultInterval;
+    private readonly records;
+    constructor(options: SubscriptionStoreOptions);
+    /**
+     * Fetch a feed WITHOUT saving it and report whether it is a usable calendar. Drives
+     * the wizard's validate-before-save step and the derived-name preview.
+     */
+    validateByFetch(url: string, requestedName?: string): Promise<ValidationResult>;
+    /**
+     * Paste-URL-and-done: validate by fetching, and on success register the subscription
+     * with an auto-derived name and default cadence, storing its events. Refuses (without
+     * saving) on a fetch/parse failure or a duplicate name, always with an honest reason.
+     */
+    add(input: AddSubscriptionInput): Promise<AddResult>;
+    /** Remove a subscription and drop its cached events. Returns whether it existed. */
+    remove(name: string): boolean;
+    list(): CalendarSubscription[];
+    get(name: string): CalendarSubscription | undefined;
+    has(name: string): boolean;
+    /** Events from the most recent successful parse of the named subscription. */
+    events(name: string): readonly CalendarEvent[];
+    /** All subscriptions' events, each tagged with its source subscription name. */
+    allEvents(): {
+        readonly name: string;
+        readonly events: readonly CalendarEvent[];
+    }[];
+    /**
+     * Refresh one subscription. Skips the network when not due unless `force`. Sends
+     * conditional-fetch validators (etag/last-modified) so an unchanged feed comes back
+     * 304 and keeps its events. Updates honest status either way.
+     */
+    refresh(name: string, opts?: {
+        force?: boolean;
+    }): Promise<RefreshReport>;
+    /** Apply a fetch result to a record, mutating status/events and returning the honest report. */
+    private applyFetch;
+    /** Refresh every subscription that is due (or never fetched). Used on boot + on demand. */
+    refreshDue(opts?: {
+        force?: boolean;
+    }): Promise<RefreshReport[]>;
+    /** Metadata snapshot for persistence; events are intentionally excluded (re-fetched on boot). */
+    snapshot(): SubscriptionSnapshot[];
+    /** Restore subscription metadata (from `snapshot()`); call `refreshDue()` afterward to load events. */
+    restore(snapshots: readonly SubscriptionSnapshot[]): void;
+    private deriveName;
+    private healthOf;
+    private toPublic;
+}
+//# sourceMappingURL=subscription-store.d.ts.map

package/dist/platform/calendar/subscription-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-store.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/subscription-store.ts"],"names":[],"mappings":"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"}

package/dist/platform/calendar/subscription-store.js

@@ -0,0 +1,293 @@
+/**
+ * subscription-store.ts — named external-calendar feed subscriptions with honest,
+ * per-subscription status. The engine that agent-side `/calendar subscribe` and the
+ * connect wizard drive.
+ *
+ * Reaches the network ONLY through an injected `FeedFetcher`, and reads time ONLY
+ * through an injected `Clock`. That is the whole IO boundary: tests supply fake
+ * feeds and a fake clock, so no test ever touches a real URL, and refresh/staleness
+ * timing is deterministic. Persistence is the CALLER's job (the agent stores the
+ * feed URL via its secret manager and the rest of the metadata in its config);
+ * `snapshot()` / `restore()` move that metadata across restarts, events re-fetched.
+ *
+ * UX shape (per Mike's least-friction rule): `add({ url })` is paste-URL-and-done —
+ * it validates by fetching, auto-derives the subscription name from the feed's
+ * X-WR-CALNAME (falling back to the URL host) when the caller gives no name, and
+ * applies a sensible default refresh interval with no mandatory knobs. Every status
+ * it reports is honest: stale carries its age, unreachable/parse-error carry the
+ * stage and detail.
+ *
+ * PURE of ambient IO — no direct fs/network/process; all IO is injected.
+ */
+import { parseIcs } from './ics-parser.js';
+/** Sensible refresh cadence for a read-only feed that rarely changes minute-to-minute. */
+export const DEFAULT_REFRESH_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+/** Never hammer a feed faster than this, even if a caller asks. */
+export const MIN_REFRESH_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+/** A feed refreshed less often than this is capped up to here. */
+export const MAX_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+/** Data is considered stale once it is older than this multiple of the interval. */
+const STALE_MULTIPLE = 2;
+/** Clamp a requested refresh interval into the safe [MIN, MAX] band. */
+function clampInterval(requested, fallback) {
+    const v = requested ?? fallback;
+    if (!Number.isFinite(v) || v <= 0)
+        return fallback;
+    return Math.max(MIN_REFRESH_INTERVAL_MS, Math.min(MAX_REFRESH_INTERVAL_MS, v));
+}
+/** Best-effort host for name/derivation fallback; never throws. */
+function urlHost(url) {
+    try {
+        return new URL(url).host || url;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Mask a feed URL for display. Google/Outlook "secret address" URLs grant read
+ * access, so a subscription's URL is secrets-adjacent — surfaces should show this,
+ * never the raw URL. Keeps the scheme+host and the last few chars, masks the middle.
+ */
+export function maskFeedUrl(url) {
+    try {
+        const u = new URL(url);
+        const tail = u.pathname.length > 6 ? u.pathname.slice(-6) : u.pathname;
+        return `${u.protocol}//${u.host}/…${tail}`;
+    }
+    catch {
+        if (url.length <= 10)
+            return '…';
+        return `${url.slice(0, 4)}…${url.slice(-4)}`;
+    }
+}
+export class SubscriptionStore {
+    fetcher;
+    clock;
+    defaultInterval;
+    records = new Map();
+    constructor(options) {
+        this.fetcher = options.fetcher;
+        this.clock = options.clock ?? (() => Date.now());
+        this.defaultInterval = clampInterval(options.defaultRefreshIntervalMs, DEFAULT_REFRESH_INTERVAL_MS);
+    }
+    /**
+     * Fetch a feed WITHOUT saving it and report whether it is a usable calendar. Drives
+     * the wizard's validate-before-save step and the derived-name preview.
+     */
+    async validateByFetch(url, requestedName) {
+        const res = await this.fetcher({ url });
+        if (res.kind === 'error') {
+            return { ok: false, stage: 'fetch', detail: res.status ? `HTTP ${res.status}: ${res.message}` : res.message };
+        }
+        if (res.kind === 'not-modified') {
+            // A cold validate should never see 304 (no validators sent); treat as fetch failure.
+            return { ok: false, stage: 'fetch', detail: 'Server returned 304 Not Modified to an unconditional request — no calendar body to validate.' };
+        }
+        const parsed = parseIcs(res.body);
+        if (parsed.events.length === 0 && parsed.skipped.length === 0 && !parsed.calendarName) {
+            return { ok: false, stage: 'parse', detail: 'Fetched, but no VEVENTs or calendar name were found — this does not look like an iCalendar feed.' };
+        }
+        const derivedName = this.deriveName(requestedName, parsed.calendarName, url);
+        return {
+            ok: true,
+            ...(parsed.calendarName !== undefined ? { calendarName: parsed.calendarName } : {}),
+            eventCount: parsed.events.length,
+            derivedName,
+        };
+    }
+    /**
+     * Paste-URL-and-done: validate by fetching, and on success register the subscription
+     * with an auto-derived name and default cadence, storing its events. Refuses (without
+     * saving) on a fetch/parse failure or a duplicate name, always with an honest reason.
+     */
+    async add(input) {
+        // Single unconditional fetch — no separate validate round trip. We fetch once,
+        // derive the name from the body, then apply that SAME result into the record.
+        const now = this.clock();
+        const res = await this.fetcher({ url: input.url });
+        if (res.kind === 'error') {
+            return { ok: false, stage: 'fetch', detail: res.status ? `HTTP ${res.status}: ${res.message}` : res.message };
+        }
+        if (res.kind === 'not-modified') {
+            return { ok: false, stage: 'fetch', detail: 'Server returned 304 Not Modified to an unconditional request — no calendar body to add.' };
+        }
+        const parsed = parseIcs(res.body);
+        if (parsed.events.length === 0 && parsed.skipped.length === 0 && !parsed.calendarName) {
+            return { ok: false, stage: 'parse', detail: 'Fetched, but no VEVENTs or calendar name were found — this does not look like an iCalendar feed.' };
+        }
+        const name = this.deriveName(input.name, parsed.calendarName, input.url);
+        const record = {
+            name,
+            url: input.url,
+            refreshIntervalMs: clampInterval(input.refreshIntervalMs, this.defaultInterval),
+            lastResult: undefined,
+            events: [],
+        };
+        this.records.set(name, record);
+        record.lastFetchedAt = now;
+        const report = this.applyFetch(record, res, now);
+        return { ok: true, subscription: this.toPublic(record), report };
+    }
+    /** Remove a subscription and drop its cached events. Returns whether it existed. */
+    remove(name) {
+        return this.records.delete(name);
+    }
+    list() {
+        return [...this.records.values()].map((r) => this.toPublic(r));
+    }
+    get(name) {
+        const r = this.records.get(name);
+        return r ? this.toPublic(r) : undefined;
+    }
+    has(name) {
+        return this.records.has(name);
+    }
+    /** Events from the most recent successful parse of the named subscription. */
+    events(name) {
+        return this.records.get(name)?.events ?? [];
+    }
+    /** All subscriptions' events, each tagged with its source subscription name. */
+    allEvents() {
+        return [...this.records.values()].map((r) => ({ name: r.name, events: r.events }));
+    }
+    /**
+     * Refresh one subscription. Skips the network when not due unless `force`. Sends
+     * conditional-fetch validators (etag/last-modified) so an unchanged feed comes back
+     * 304 and keeps its events. Updates honest status either way.
+     */
+    async refresh(name, opts = {}) {
+        const r = this.records.get(name);
+        if (!r)
+            return { name, outcome: 'skipped', health: 'never-fetched', detail: `No subscription named '${name}'.` };
+        const now = this.clock();
+        if (!opts.force && r.lastFetchedAt !== undefined && now - r.lastFetchedAt < r.refreshIntervalMs) {
+            return { name, outcome: 'skipped', health: this.healthOf(r, now), ...(r.eventCount !== undefined ? { eventCount: r.eventCount } : {}), detail: 'Not due for refresh yet.' };
+        }
+        r.lastFetchedAt = now;
+        const res = await this.fetcher({
+            url: r.url,
+            ...(r.etag !== undefined ? { etag: r.etag } : {}),
+            ...(r.lastModified !== undefined ? { lastModified: r.lastModified } : {}),
+        });
+        return this.applyFetch(r, res, now);
+    }
+    /** Apply a fetch result to a record, mutating status/events and returning the honest report. */
+    applyFetch(r, res, now) {
+        const name = r.name;
+        if (res.kind === 'error') {
+            r.lastResult = 'unreachable';
+            r.lastDetail = res.status ? `HTTP ${res.status}: ${res.message}` : res.message;
+            return { name, outcome: 'unreachable', health: this.healthOf(r, now), ...(r.eventCount !== undefined ? { eventCount: r.eventCount } : {}), detail: r.lastDetail };
+        }
+        if (res.kind === 'not-modified') {
+            r.lastResult = 'not-modified';
+            r.lastSucceededAt = now;
+            if (res.etag !== undefined)
+                r.etag = res.etag;
+            if (res.lastModified !== undefined)
+                r.lastModified = res.lastModified;
+            r.lastDetail = undefined;
+            return { name, outcome: 'not-modified', health: this.healthOf(r, now), ...(r.eventCount !== undefined ? { eventCount: r.eventCount } : {}) };
+        }
+        const parsed = parseIcs(res.body);
+        if (parsed.events.length === 0 && parsed.skipped.length > 0) {
+            r.lastResult = 'parse-error';
+            r.lastDetail = `Fetched, but every VEVENT was unusable: ${parsed.skipped[0]?.message ?? 'no usable events'}`;
+            return { name, outcome: 'parse-error', health: this.healthOf(r, now), detail: r.lastDetail };
+        }
+        r.events = [...parsed.events];
+        r.eventCount = parsed.events.length;
+        r.lastResult = 'ok';
+        r.lastSucceededAt = now;
+        r.lastDetail = parsed.diagnostics.length > 0 ? `${parsed.diagnostics.length} note(s): ${parsed.diagnostics[0]?.message ?? ''}` : undefined;
+        if (res.etag !== undefined)
+            r.etag = res.etag;
+        if (res.lastModified !== undefined)
+            r.lastModified = res.lastModified;
+        return { name, outcome: 'updated', health: 'ok', eventCount: r.eventCount, ...(r.lastDetail !== undefined ? { detail: r.lastDetail } : {}) };
+    }
+    /** Refresh every subscription that is due (or never fetched). Used on boot + on demand. */
+    async refreshDue(opts = {}) {
+        const reports = [];
+        for (const name of this.records.keys()) {
+            reports.push(await this.refresh(name, opts));
+        }
+        return reports;
+    }
+    /** Metadata snapshot for persistence; events are intentionally excluded (re-fetched on boot). */
+    snapshot() {
+        return [...this.records.values()].map((r) => ({
+            name: r.name,
+            url: r.url,
+            refreshIntervalMs: r.refreshIntervalMs,
+            ...(r.lastFetchedAt !== undefined ? { lastFetchedAt: r.lastFetchedAt } : {}),
+            ...(r.lastSucceededAt !== undefined ? { lastSucceededAt: r.lastSucceededAt } : {}),
+            ...(r.etag !== undefined ? { etag: r.etag } : {}),
+            ...(r.lastModified !== undefined ? { lastModified: r.lastModified } : {}),
+        }));
+    }
+    /** Restore subscription metadata (from `snapshot()`); call `refreshDue()` afterward to load events. */
+    restore(snapshots) {
+        for (const s of snapshots) {
+            this.records.set(s.name, {
+                name: s.name,
+                url: s.url,
+                refreshIntervalMs: clampInterval(s.refreshIntervalMs, this.defaultInterval),
+                ...(s.lastFetchedAt !== undefined ? { lastFetchedAt: s.lastFetchedAt } : {}),
+                ...(s.lastSucceededAt !== undefined ? { lastSucceededAt: s.lastSucceededAt } : {}),
+                ...(s.etag !== undefined ? { etag: s.etag } : {}),
+                ...(s.lastModified !== undefined ? { lastModified: s.lastModified } : {}),
+                lastResult: undefined,
+                events: [],
+            });
+        }
+    }
+    deriveName(requested, calendarName, url) {
+        const candidate = (requested?.trim() || calendarName?.trim() || urlHost(url)).replace(/\s+/g, ' ').trim();
+        let name = candidate || urlHost(url);
+        // De-duplicate against existing names so an unnamed second Google feed still lands.
+        if (this.records.has(name)) {
+            let n = 2;
+            while (this.records.has(`${name} (${n})`))
+                n++;
+            name = `${name} (${n})`;
+        }
+        return name;
+    }
+    healthOf(r, now) {
+        if (r.lastResult === undefined)
+            return 'never-fetched';
+        if (r.lastResult === 'unreachable')
+            return 'unreachable';
+        if (r.lastResult === 'parse-error')
+            return 'parse-error';
+        if (r.lastSucceededAt === undefined)
+            return 'never-fetched';
+        const age = now - r.lastSucceededAt;
+        if (age > r.refreshIntervalMs * STALE_MULTIPLE)
+            return 'stale';
+        return 'ok';
+    }
+    toPublic(r) {
+        const now = this.clock();
+        const health = this.healthOf(r, now);
+        let detail = r.lastDetail;
+        if (health === 'stale' && r.lastSucceededAt !== undefined) {
+            const ageMin = Math.round((now - r.lastSucceededAt) / 60000);
+            detail = `Last updated ${ageMin} min ago (past the ${Math.round(r.refreshIntervalMs / 60000)} min refresh window).`;
+        }
+        return {
+            name: r.name,
+            url: r.url,
+            refreshIntervalMs: r.refreshIntervalMs,
+            ...(r.lastFetchedAt !== undefined ? { lastFetchedAt: r.lastFetchedAt } : {}),
+            ...(r.lastSucceededAt !== undefined ? { lastSucceededAt: r.lastSucceededAt } : {}),
+            ...(r.etag !== undefined ? { etag: r.etag } : {}),
+            ...(r.lastModified !== undefined ? { lastModified: r.lastModified } : {}),
+            health,
+            ...(detail !== undefined ? { detail } : {}),
+            ...(r.eventCount !== undefined ? { eventCount: r.eventCount } : {}),
+        };
+    }
+}