@vellumai/assistant 0.3.0

package/src/__tests__/ratelimit.test.ts

@@ -0,0 +1,297 @@
+import { describe, test, expect, mock } from 'bun:test';
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+import { RateLimitProvider } from '../providers/ratelimit.js';
+import { RateLimitError } from '../util/errors.js';
+import type { Provider, ProviderResponse, Message } from '../providers/types.js';
+import type { RateLimitConfig } from '../config/types.js';
+
+function makeProvider(response?: Partial<ProviderResponse>): Provider {
+  return {
+    name: 'mock',
+    sendMessage: async () => ({
+      content: [{ type: 'text' as const, text: 'ok' }],
+      model: 'test-model',
+      usage: { inputTokens: 100, outputTokens: 50 },
+      stopReason: 'end_turn',
+      ...response,
+    }),
+  };
+}
+
+const messages: Message[] = [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }];
+
+describe('RateLimitProvider', () => {
+  describe('request rate limiting', () => {
+    test('allows requests under the limit', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 5, maxTokensPerSession: 0 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      for (let i = 0; i < 5; i++) {
+        await provider.sendMessage(messages);
+      }
+    });
+
+    test('throws RateLimitError when exceeding request limit', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 2, maxTokensPerSession: 0 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      await provider.sendMessage(messages);
+      await provider.sendMessage(messages);
+
+      expect(provider.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+
+    test('unlimited when maxRequestsPerMinute is 0', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 0 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      for (let i = 0; i < 100; i++) {
+        await provider.sendMessage(messages);
+      }
+    });
+  });
+
+  describe('session token limiting', () => {
+    test('allows requests under the token budget', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 1000 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      // Each call uses 150 tokens (100 input + 50 output)
+      for (let i = 0; i < 6; i++) {
+        await provider.sendMessage(messages);
+      }
+      // 6 * 150 = 900, still under 1000
+    });
+
+    test('throws RateLimitError when token budget exhausted', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 300 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      // 150 tokens per call
+      await provider.sendMessage(messages); // 150
+      await provider.sendMessage(messages); // 300
+
+      expect(provider.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+
+    test('unlimited when maxTokensPerSession is 0', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 0 };
+      const provider = new RateLimitProvider(
+        makeProvider({ usage: { inputTokens: 10000, outputTokens: 10000 } }),
+        config,
+      );
+
+      for (let i = 0; i < 10; i++) {
+        await provider.sendMessage(messages);
+      }
+    });
+  });
+
+  describe('passthrough behavior', () => {
+    test('delegates to inner provider', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 0 };
+      const inner = makeProvider({ model: 'custom-model' });
+      const provider = new RateLimitProvider(inner, config);
+
+      const response = await provider.sendMessage(messages);
+      expect(response.model).toBe('custom-model');
+    });
+
+    test('preserves provider name', () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 0 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+      expect(provider.name).toBe('mock');
+    });
+
+    test('passes through all arguments to inner provider', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 0, maxTokensPerSession: 0 };
+      let receivedArgs: unknown[] = [];
+      const inner: Provider = {
+        name: 'spy',
+        sendMessage: async (...args) => {
+          receivedArgs = args;
+          return {
+            content: [{ type: 'text' as const, text: '' }],
+            model: 'test',
+            usage: { inputTokens: 0, outputTokens: 0 },
+            stopReason: 'end_turn',
+          };
+        },
+      };
+      const provider = new RateLimitProvider(inner, config);
+
+      const tools = [{ name: 'test', description: 'test', input_schema: {} }];
+      const systemPrompt = 'hello';
+      const options = { config: { max_tokens: 100 } };
+
+      await provider.sendMessage(messages, tools, systemPrompt, options);
+
+      expect(receivedArgs[0]).toBe(messages);
+      expect(receivedArgs[1]).toBe(tools);
+      expect(receivedArgs[2]).toBe(systemPrompt);
+      expect(receivedArgs[3]).toBe(options);
+    });
+  });
+
+  describe('combined limits', () => {
+    test('enforces both limits simultaneously', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 10, maxTokensPerSession: 300 };
+      const provider = new RateLimitProvider(makeProvider(), config);
+
+      // Token limit should hit first (2 * 150 = 300)
+      await provider.sendMessage(messages);
+      await provider.sendMessage(messages);
+
+      expect(provider.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+  });
+
+  describe('shared request timestamps', () => {
+    test('multiple providers sharing timestamps enforce a global rate limit', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 2, maxTokensPerSession: 0 };
+      const shared: number[] = [];
+      const provider1 = new RateLimitProvider(makeProvider(), config, shared);
+      const provider2 = new RateLimitProvider(makeProvider(), config, shared);
+
+      // Each provider sends one request — together they hit the limit of 2
+      await provider1.sendMessage(messages);
+      await provider2.sendMessage(messages);
+
+      // A third request from either provider should be rate-limited
+      await expect(provider1.sendMessage(messages)).rejects.toThrow(RateLimitError);
+      await expect(provider2.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+
+    test('out-of-order timestamps are pruned correctly (clock skew)', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 3, maxTokensPerSession: 0 };
+      const shared: number[] = [];
+      const provider = new RateLimitProvider(makeProvider(), config, shared);
+
+      // Simulate clock skew: insert an old timestamp between newer ones
+      const now = Date.now();
+      shared.push(now);                   // current
+      shared.push(now - 120_000);         // 2 minutes ago (expired)
+      shared.push(now);                   // current
+
+      // enforceRequestRate should prune the expired entry regardless of position
+      await provider.sendMessage(messages);
+
+      // 2 fresh timestamps from before + 1 from the new call = 3 (the expired one was removed)
+      expect(shared.length).toBe(3);
+    });
+
+    test('waitSec uses actual oldest timestamp under clock skew', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 2, maxTokensPerSession: 0 };
+      const shared: number[] = [];
+      const provider = new RateLimitProvider(makeProvider(), config, shared);
+
+      // Simulate out-of-order timestamps: newer one first, older one second
+      const now = Date.now();
+      shared.push(now);               // newest
+      shared.push(now - 30_000);      // 30s ago (oldest in window)
+
+      // Next request should be rate-limited with ~30s wait (not 60s)
+      try {
+        await provider.sendMessage(messages);
+        expect(true).toBe(false); // should not reach
+      } catch (err) {
+        expect(err).toBeInstanceOf(RateLimitError);
+        const msg = (err as RateLimitError).message;
+        // Wait time should be ~30s, not 60s
+        const waitMatch = msg.match(/(\d+)s/);
+        expect(waitMatch).toBeTruthy();
+        const waitSec = parseInt(waitMatch![1], 10);
+        expect(waitSec).toBeLessThanOrEqual(31);
+        expect(waitSec).toBeGreaterThanOrEqual(29);
+      }
+    });
+
+    test('handles large timestamp arrays without stack overflow', async () => {
+      const highLimit = 200_000;
+      const config: RateLimitConfig = { maxRequestsPerMinute: highLimit, maxTokensPerSession: 0 };
+      const shared: number[] = [];
+      const provider = new RateLimitProvider(makeProvider(), config, shared);
+
+      // Fill with timestamps that are all within the window
+      const now = Date.now();
+      for (let i = 0; i < highLimit; i++) {
+        shared.push(now - Math.floor(Math.random() * 59_000));
+      }
+
+      // This should throw RateLimitError, not RangeError
+      await expect(provider.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+
+    test('shared array reference survives pruning', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 100, maxTokensPerSession: 0 };
+      const shared: number[] = [];
+      const provider1 = new RateLimitProvider(makeProvider(), config, shared);
+      const provider2 = new RateLimitProvider(makeProvider(), config, shared);
+
+      // Provider 1 sends a request, adding a timestamp to the shared array
+      await provider1.sendMessage(messages);
+      expect(shared.length).toBe(1);
+
+      // Provider 2 sends a request — enforceRequestRate prunes expired
+      // entries, but the shared reference must still be the same array
+      await provider2.sendMessage(messages);
+      expect(shared.length).toBe(2);
+
+      // Both providers still share the same underlying array
+      await provider1.sendMessage(messages);
+      expect(shared.length).toBe(3);
+    });
+  });
+
+  describe('race condition prevention', () => {
+    test('concurrent calls are rate-limited because timestamp is recorded before await', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 1, maxTokensPerSession: 0 };
+      // Slow provider that yields to the event loop
+      const inner: Provider = {
+        name: 'slow',
+        sendMessage: async () => {
+          await new Promise((r) => setTimeout(r, 10));
+          return {
+            content: [{ type: 'text' as const, text: '' }],
+            model: 'test',
+            usage: { inputTokens: 0, outputTokens: 0 },
+            stopReason: 'end_turn',
+          };
+        },
+      };
+      const provider = new RateLimitProvider(inner, config);
+
+      // Fire two concurrent requests — second should fail
+      const results = await Promise.allSettled([
+        provider.sendMessage(messages),
+        provider.sendMessage(messages),
+      ]);
+
+      const fulfilled = results.filter((r) => r.status === 'fulfilled');
+      const rejected = results.filter((r) => r.status === 'rejected');
+      expect(fulfilled.length).toBe(1);
+      expect(rejected.length).toBe(1);
+    });
+
+    test('failed inner calls still count toward request rate', async () => {
+      const config: RateLimitConfig = { maxRequestsPerMinute: 1, maxTokensPerSession: 0 };
+      const inner: Provider = {
+        name: 'failing',
+        sendMessage: async () => { throw new Error('provider error'); },
+      };
+      const provider = new RateLimitProvider(inner, config);
+
+      // First call fails at the provider level
+      await expect(provider.sendMessage(messages)).rejects.toThrow('provider error');
+
+      // Second call should be rate-limited (timestamp was recorded before the failed await)
+      await expect(provider.sendMessage(messages)).rejects.toThrow(RateLimitError);
+    });
+  });
+});

package/src/__tests__/recurrence-engine-rruleset.test.ts

@@ -0,0 +1,175 @@
+import { describe, test, expect } from 'bun:test';
+import { isValidScheduleExpression, computeNextRunAt } from '../schedule/recurrence-engine.js';
+
+describe('RRULE set engine support', () => {
+  test('multiple RRULE lines are unioned — next run is earliest', () => {
+    // Daily at 9am + Weekly on Mondays at 3pm, starting Jan 1 2099
+    const expr = [
+      'DTSTART:20990101T090000Z',
+      'RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+      'RRULE:FREQ=WEEKLY;BYDAY=MO;BYHOUR=15;BYMINUTE=0;BYSECOND=0',
+    ].join('\n');
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr });
+    expect(next).toBeGreaterThan(Date.now());
+  });
+
+  test('RRULE + EXDATE excludes matching occurrence', () => {
+    // Daily starting Jan 1 2099, exclude Jan 2
+    const expr = [
+      'DTSTART:20990101T090000Z',
+      'RRULE:FREQ=DAILY;COUNT=5',
+      'EXDATE:20990102T090000Z',
+    ].join('\n');
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+    // First occurrence: Jan 1, second should skip Jan 2 and be Jan 3
+    const jan1 = new Date('2099-01-01T09:00:00Z').getTime();
+    const jan2 = new Date('2099-01-02T09:00:00Z').getTime();
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr }, jan1 + 1);
+    // Should not be Jan 2 (excluded)
+    expect(next).not.toBe(jan2);
+  });
+
+  test('RDATE adds ad-hoc occurrence', () => {
+    // Weekly on Mondays + an extra occurrence on Jan 15 2099 (Wednesday)
+    const expr = [
+      'DTSTART:20990106T090000Z',
+      'RRULE:FREQ=WEEKLY;BYDAY=MO',
+      'RDATE:20990115T090000Z',
+    ].join('\n');
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+  });
+
+  test('unknown line is rejected', () => {
+    const expr = [
+      'DTSTART:20990101T090000Z',
+      'RRULE:FREQ=DAILY',
+      'SUMMARY:My event',
+    ].join('\n');
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(false);
+  });
+
+  test('expression without DTSTART is rejected', () => {
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: 'RRULE:FREQ=DAILY' })).toBe(false);
+  });
+
+  test('expression without inclusion source is rejected', () => {
+    const expr = 'DTSTART:20990101T090000Z\nEXDATE:20990102T090000Z';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(false);
+  });
+
+  test('escaped newlines are normalized', () => {
+    const expr = 'DTSTART:20990101T090000Z\\nRRULE:FREQ=DAILY';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr });
+    expect(next).toBeGreaterThan(Date.now());
+  });
+
+  test('existing single RRULE still works', () => {
+    const expr = 'DTSTART:20990101T090000Z\nRRULE:FREQ=DAILY';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+  });
+
+  test('existing cron still works', () => {
+    expect(isValidScheduleExpression({ syntax: 'cron', expression: '0 9 * * 1-5' })).toBe(true);
+    const next = computeNextRunAt({ syntax: 'cron', expression: '* * * * *' });
+    expect(next).toBeGreaterThan(Date.now() - 1);
+  });
+});
+
+// ── EXRULE behavioral tests ──────────────────────────────────────────
+
+describe('EXRULE engine behavior', () => {
+  test('EXRULE excludes matching occurrences from daily series', () => {
+    // RRULE: every day at 09:00 starting Jan 1 2099
+    // EXRULE: every Saturday and Sunday (weekends)
+    // Expected: weekday occurrences only
+    const expr = [
+      'DTSTART:20990101T090000Z',
+      'RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+      'EXRULE:FREQ=WEEKLY;BYDAY=SA,SU;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+    ].join('\n');
+
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+
+    // Jan 1 2099 is a Thursday. Enumerate the first several occurrences
+    // and verify that no Saturday (Jan 3) or Sunday (Jan 4) appears.
+    const thu = new Date('2099-01-01T09:00:00Z').getTime(); // Thu
+    const fri = new Date('2099-01-02T09:00:00Z').getTime(); // Fri
+    const sat = new Date('2099-01-03T09:00:00Z').getTime(); // Sat
+    const sun = new Date('2099-01-04T09:00:00Z').getTime(); // Sun
+    const mon = new Date('2099-01-05T09:00:00Z').getTime(); // Mon
+
+    // After Thu -> should be Fri (not Sat/Sun)
+    const afterThu = computeNextRunAt({ syntax: 'rrule', expression: expr }, thu + 1);
+    expect(afterThu).toBe(fri);
+
+    // After Fri -> should skip Sat+Sun, land on Mon
+    const afterFri = computeNextRunAt({ syntax: 'rrule', expression: expr }, fri + 1);
+    expect(afterFri).toBe(mon);
+
+    // Explicitly confirm Sat and Sun are never returned
+    expect(afterFri).not.toBe(sat);
+    expect(afterFri).not.toBe(sun);
+  });
+
+  test('EXRULE with FREQ acts as repeating exclusion series', () => {
+    // RRULE: every day starting Jan 1 2099
+    // EXRULE: every 3rd day starting Jan 1 2099 (excludes Jan 1, Jan 4, Jan 7, ...)
+    const expr = [
+      'DTSTART:20990101T090000Z',
+      'RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+      'EXRULE:FREQ=DAILY;INTERVAL=3;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+    ].join('\n');
+
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+
+    const jan1 = new Date('2099-01-01T09:00:00Z').getTime();
+    const jan2 = new Date('2099-01-02T09:00:00Z').getTime();
+    const jan3 = new Date('2099-01-03T09:00:00Z').getTime();
+    const jan4 = new Date('2099-01-04T09:00:00Z').getTime();
+    const jan5 = new Date('2099-01-05T09:00:00Z').getTime();
+
+    // Jan 1 is excluded (EXRULE fires on DTSTART). First occurrence after
+    // DTSTART should be Jan 2.
+    const first = computeNextRunAt({ syntax: 'rrule', expression: expr }, jan1 - 1);
+    expect(first).toBe(jan2);
+
+    // After Jan 2 -> Jan 3 (Jan 3 not excluded)
+    const second = computeNextRunAt({ syntax: 'rrule', expression: expr }, jan2 + 1);
+    expect(second).toBe(jan3);
+
+    // After Jan 3 -> should skip Jan 4 (excluded, 3 days after Jan 1) -> Jan 5
+    const third = computeNextRunAt({ syntax: 'rrule', expression: expr }, jan3 + 1);
+    expect(third).toBe(jan5);
+    expect(third).not.toBe(jan4);
+  });
+
+  test('EXRULE does not affect non-matching occurrences', () => {
+    // RRULE: every weekday (Mon-Fri) at 09:00
+    // EXRULE: every Saturday at 09:00 (no overlap with weekday rule)
+    // Expected: all weekday occurrences remain intact
+    const expr = [
+      'DTSTART:20990105T090000Z',
+      'RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+      'EXRULE:FREQ=WEEKLY;BYDAY=SA;BYHOUR=9;BYMINUTE=0;BYSECOND=0',
+    ].join('\n');
+
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+
+    // Jan 5 2099 is a Monday. Verify all five weekdays in the first week appear.
+    const mon = new Date('2099-01-05T09:00:00Z').getTime();
+    const tue = new Date('2099-01-06T09:00:00Z').getTime();
+    const wed = new Date('2099-01-07T09:00:00Z').getTime();
+    const thu = new Date('2099-01-08T09:00:00Z').getTime();
+    const fri = new Date('2099-01-09T09:00:00Z').getTime();
+    const nextMon = new Date('2099-01-12T09:00:00Z').getTime();
+
+    expect(computeNextRunAt({ syntax: 'rrule', expression: expr }, mon + 1)).toBe(tue);
+    expect(computeNextRunAt({ syntax: 'rrule', expression: expr }, tue + 1)).toBe(wed);
+    expect(computeNextRunAt({ syntax: 'rrule', expression: expr }, wed + 1)).toBe(thu);
+    expect(computeNextRunAt({ syntax: 'rrule', expression: expr }, thu + 1)).toBe(fri);
+    // After Fri -> skips weekend entirely (Sat excluded + Sun not in RRULE) -> Mon
+    expect(computeNextRunAt({ syntax: 'rrule', expression: expr }, fri + 1)).toBe(nextMon);
+  });
+});

package/src/__tests__/recurrence-engine.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from 'bun:test';
+import { isValidScheduleExpression, computeNextRunAt } from '../schedule/recurrence-engine.js';
+
+describe('recurrence engine — cron', () => {
+  test('validates valid cron expressions', () => {
+    expect(isValidScheduleExpression({ syntax: 'cron', expression: '0 9 * * 1-5' })).toBe(true);
+    expect(isValidScheduleExpression({ syntax: 'cron', expression: '*/5 * * * *' })).toBe(true);
+  });
+
+  test('rejects invalid cron expressions', () => {
+    expect(isValidScheduleExpression({ syntax: 'cron', expression: 'not valid' })).toBe(false);
+    expect(isValidScheduleExpression({ syntax: 'cron', expression: '' })).toBe(false);
+  });
+
+  test('computes next run for cron', () => {
+    const now = Date.now();
+    const next = computeNextRunAt({ syntax: 'cron', expression: '* * * * *' }, now);
+    expect(next).toBeGreaterThan(now - 1);
+    // Next minute should be within 60 seconds
+    expect(next - now).toBeLessThanOrEqual(60_000);
+  });
+});
+
+describe('recurrence engine — rrule', () => {
+  test('validates RRULE with DTSTART', () => {
+    const expr = 'DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+  });
+
+  test('rejects RRULE without DTSTART', () => {
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: 'RRULE:FREQ=DAILY' })).toBe(false);
+  });
+
+  test('accepts RRULE set constructs', () => {
+    const withExdate = 'DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY\nEXDATE:20250105T090000Z';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: withExdate })).toBe(true);
+
+    const withRdate = 'DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY\nRDATE:20250115T090000Z';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: withRdate })).toBe(true);
+
+    const multiRrule = 'DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY\nRRULE:FREQ=WEEKLY';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: multiRrule })).toBe(true);
+  });
+
+  test('computes next run for RRULE with future DTSTART', () => {
+    // Use a date far in the future to ensure the test is stable
+    const futureDate = new Date('2099-01-01T09:00:00Z');
+    const expr = 'DTSTART:20990101T090000Z\nRRULE:FREQ=DAILY';
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr });
+    expect(next).toBeGreaterThanOrEqual(futureDate.getTime());
+  });
+
+  test('throws when RRULE has no future runs (UNTIL in past)', () => {
+    const expr = 'DTSTART:20200101T090000Z\nRRULE:FREQ=DAILY;UNTIL=20200105T090000Z';
+    expect(() => computeNextRunAt({ syntax: 'rrule', expression: expr })).toThrow(/no upcoming runs/);
+  });
+
+  test('throws for RRULE missing DTSTART in computeNextRunAt', () => {
+    expect(() => computeNextRunAt({ syntax: 'rrule', expression: 'RRULE:FREQ=DAILY' })).toThrow(/DTSTART/);
+  });
+
+  test('preserves TZID parameter values when normalizing lowercase prefixes', () => {
+    // TZID contains case-sensitive timezone names (e.g. America/New_York)
+    // that must not be uppercased during prefix normalization.
+    const expr = 'dtstart;TZID=America/New_York:20990601T090000\nrrule:FREQ=DAILY';
+    expect(isValidScheduleExpression({ syntax: 'rrule', expression: expr })).toBe(true);
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr });
+    expect(next).toBeGreaterThan(Date.now());
+  });
+
+  test('computes next run for RRULE with EXDATE set construct', () => {
+    const expr = 'DTSTART:20990101T090000Z\nRRULE:FREQ=DAILY\nEXDATE:20990101T090000Z';
+    const next = computeNextRunAt({ syntax: 'rrule', expression: expr });
+    // Should skip the excluded date and return January 2
+    const jan2 = new Date('2099-01-02T09:00:00Z').getTime();
+    expect(next).toBe(jan2);
+  });
+});

package/src/__tests__/recurrence-types.test.ts

@@ -0,0 +1,79 @@
+import { describe, test, expect } from 'bun:test';
+import { detectScheduleSyntax, normalizeScheduleSyntax } from '../schedule/recurrence-types.js';
+
+describe('detectScheduleSyntax', () => {
+  test('detects cron for standard 5-field expressions', () => {
+    expect(detectScheduleSyntax('0 9 * * 1-5')).toBe('cron');
+    expect(detectScheduleSyntax('*/5 * * * *')).toBe('cron');
+    expect(detectScheduleSyntax('30 14 1 * *')).toBe('cron');
+    expect(detectScheduleSyntax('0 0 * * 0')).toBe('cron');
+  });
+
+  test('detects RRULE for RRULE: prefix', () => {
+    expect(detectScheduleSyntax('RRULE:FREQ=DAILY;BYHOUR=9;BYMINUTE=0')).toBe('rrule');
+  });
+
+  test('detects RRULE for DTSTART + RRULE multiline', () => {
+    expect(detectScheduleSyntax('DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY')).toBe('rrule');
+  });
+
+  test('detects RRULE for expression containing FREQ=', () => {
+    expect(detectScheduleSyntax('FREQ=WEEKLY;BYDAY=MO,WE,FR')).toBe('rrule');
+  });
+
+  test('returns null for empty/invalid input', () => {
+    expect(detectScheduleSyntax('')).toBeNull();
+    expect(detectScheduleSyntax('   ')).toBeNull();
+    expect(detectScheduleSyntax('hello world')).toBeNull();
+    expect(detectScheduleSyntax('not a schedule expression at all and is long')).toBeNull();
+  });
+
+  test('returns null for ambiguous expressions', () => {
+    // Single word that is not 5 fields and not RRULE
+    expect(detectScheduleSyntax('daily')).toBeNull();
+  });
+});
+
+describe('normalizeScheduleSyntax', () => {
+  test('uses explicit syntax + expression when both provided', () => {
+    const result = normalizeScheduleSyntax({
+      syntax: 'rrule',
+      expression: 'RRULE:FREQ=DAILY',
+    });
+    expect(result).toEqual({ syntax: 'rrule', expression: 'RRULE:FREQ=DAILY' });
+  });
+
+  test('auto-detects syntax from expression', () => {
+    const cronResult = normalizeScheduleSyntax({ expression: '0 9 * * 1-5' });
+    expect(cronResult).toEqual({ syntax: 'cron', expression: '0 9 * * 1-5' });
+
+    const rruleResult = normalizeScheduleSyntax({ expression: 'RRULE:FREQ=DAILY' });
+    expect(rruleResult).toEqual({ syntax: 'rrule', expression: 'RRULE:FREQ=DAILY' });
+  });
+
+  test('falls back to legacyCronExpression', () => {
+    const result = normalizeScheduleSyntax({ legacyCronExpression: '0 9 * * *' });
+    expect(result).toEqual({ syntax: 'cron', expression: '0 9 * * *' });
+  });
+
+  test('honors explicit syntax hint in legacyCronExpression fallback', () => {
+    const result = normalizeScheduleSyntax({
+      syntax: 'rrule',
+      legacyCronExpression: '0 9 * * *',
+    });
+    expect(result).toEqual({ syntax: 'rrule', expression: '0 9 * * *' });
+  });
+
+  test('returns null when nothing is provided', () => {
+    expect(normalizeScheduleSyntax({})).toBeNull();
+  });
+
+  test('returns null when expression is ambiguous and no syntax hint', () => {
+    expect(normalizeScheduleSyntax({ expression: 'daily' })).toBeNull();
+  });
+
+  test('trusts explicit syntax when auto-detection fails', () => {
+    const result = normalizeScheduleSyntax({ syntax: 'cron', expression: 'some-custom-expr' });
+    expect(result).toEqual({ syntax: 'cron', expression: 'some-custom-expr' });
+  });
+});