---
phase: 06-ux-polish
plan: '02'
subsystem: api/broker
tags: [tdd, rrule, recurrence, serialization, ical.js, zod]
dependency_graph:
  requires: []
  provides:
    - assembleRruleString helper in apps/api/src/broker/outboxWorker.ts
    - recurrenceUntil/recurrenceCount fields in outboxPayloadSchema + eventFieldsSchema
  affects:
    - apps/api/src/broker/outboxWorker.ts
    - apps/api/src/routes/events.ts
    - apps/api/tests/broker/vevent.test.ts
    - apps/api/tests/broker/outboxWorker.test.ts
tech_stack:
  added: []
  patterns:
    - ical.js ICAL.Recur.fromString + rruleProp.setValue for RRULE serialization
    - assembleRruleString count-wins-over-until mutual exclusion (RFC 5545 §3.3.10)
    - Series-edit Pitfall 3: strip UNTIL/COUNT via regex before re-applying new bound
key_files:
  created: []
  modified:
    - apps/api/src/broker/outboxWorker.ts
    - apps/api/src/routes/events.ts
    - apps/api/tests/broker/vevent.test.ts
    - apps/api/tests/broker/outboxWorker.test.ts
decisions:
  - 'assembleRruleString: COUNT takes precedence over UNTIL (mutual exclusion, RFC 5545 §3.3.10)'
  - 'Timed UNTIL serializes as YYYYMMDDTHHMMSSZ (end-of-UTC-day T235959Z) per RESEARCH Pitfall 2'
  - "hasExplicitRecurrence check gates assembleRruleString; recurrence:'none' explicitly yields undefined (no RRULE)"
  - 'Series-edit bound-only change: regex strips existing UNTIL/COUNT from preserved RRULE before re-applying new bound'
metrics:
  duration_minutes: 8
  completed_date: '2026-06-10'
  tasks_completed: 2
  files_modified: 4
---

# Phase 06 Plan 02: RRULE UNTIL/COUNT Serialization + FREQ Persistence Summary

**One-liner:** RRULE UNTIL/COUNT serialization with value-type-matching (DATE vs DATETIME UTC) via `assembleRruleString`, wired into both create + update outbox branches, with a FREQ=DAILY regression lock.

## Tasks Completed

| #   | Name                                                                            | Commit  | Type |
| --- | ------------------------------------------------------------------------------- | ------- | ---- |
| 1   | RED — failing tests for UNTIL/COUNT serialization + FREQ-persistence regression | a59455a | test |
| 2   | GREEN — assembleRruleString + Zod schema acceptance, wired into the write path  | d2abb91 | feat |

## What Was Built

### Task 1: RED

Added failing tests to two files:

**`vevent.test.ts`** — three new serialization assertions confirming ical.js 2.2.1 handles UNTIL/COUNT correctly via the existing `ICAL.Recur.fromString` path:

- `FREQ=WEEKLY;COUNT=5` → `RRULE:FREQ=WEEKLY;COUNT=5`
- `FREQ=DAILY;UNTIL=20260630` (all-day) → contains `RRULE:FREQ=DAILY;UNTIL=20260630`, does NOT contain `T235959Z`
- `FREQ=WEEKLY;UNTIL=20260630T235959Z` (timed) → `RRULE:FREQ=WEEKLY;UNTIL=20260630T235959Z`

**`outboxWorker.test.ts`** — two new describe blocks:

- `assembleRruleString (D-06)`: 6 cases covering COUNT wins, UNTIL DATE/DATETIME, COUNT-wins-over-UNTIL mutual exclusion, base preset unchanged
- `FREQ persistence (D-07 regression)`: 1 case asserting daily-recurrence payload emits `RRULE:FREQ=DAILY`

RED confirmed: `assembleRruleString is not a function` (6 failing tests).

### Task 2: GREEN

**`apps/api/src/broker/outboxWorker.ts`:**

- Added `recurrenceUntil: z.string().max(10).optional()` and `recurrenceCount: z.number().int().min(1).optional()` to `outboxPayloadSchema` (T-06-02 mitigations)
- Implemented and exported `assembleRruleString(basePreset, until?, count?, allDay?)` with JSDoc (D-06)
- Wired `assembleRruleString` into both create and update dispatch branches
- Fixed precedence: `hasExplicitRecurrence` checked first (covers `recurrence:'none'` → explicitly yields `undefined`); `preservedRrule` only used when no explicit recurrence
- Series-edit Pitfall 3: when a bound-only change applies to a preserved RRULE, strips `UNTIL/COUNT` via `/;(UNTIL|COUNT)=[^;]*/g` before re-applying

**`apps/api/src/routes/events.ts`:**

- Added `recurrenceUntil: z.string().max(10).optional()` and `recurrenceCount: z.number().int().min(1).optional()` to `eventFieldsSchema`

All 39 tests pass. The previously passing CR-01 (`recurrence:'none' wins over _preservedRrule`) was initially broken by the change and auto-fixed (Rule 1 bug: logic precedence error).

## TDD Gate Compliance

| Gate                          | Status                                                    |
| ----------------------------- | --------------------------------------------------------- |
| RED commit (`test(06-02):`)   | a59455a — exists, confirmed failing                       |
| GREEN commit (`feat(06-02):`) | d2abb91 — follows RED commit                              |
| Commit order                  | test(06-02) precedes feat(06-02) — verified via `git log` |

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed hasExplicitRecurrence precedence for recurrence:'none'**

- **Found during:** Task 2 (GREEN)
- **Issue:** Initial implementation used `if (hasExplicitRecurrence && rruleFromPayload)` — when `recurrence:'none'`, `rruleFromPayload` is `undefined`, so the condition was `false`, incorrectly falling through to `else if (preservedRrule)` and emitting an RRULE even though the user explicitly selected 'none'. Broke existing `CR-01: explicit recurrence:'none' wins` test.
- **Fix:** Changed to `if (hasExplicitRecurrence)` with an inner ternary: if `rruleFromPayload` is truthy, assemble with bound; otherwise `undefined`. Applied identically to both create and update branches.
- **Files modified:** `apps/api/src/broker/outboxWorker.ts`
- **Commit:** d2abb91 (folded into GREEN commit)

## Verification Evidence

```
cd apps/api && pnpm vitest run tests/broker/vevent.test.ts tests/broker/outboxWorker.test.ts
Test Files  2 passed (2)
Tests  39 passed (39)
```

```
grep -n "recurrenceUntil" apps/api/src/routes/events.ts apps/api/src/broker/outboxWorker.ts
events.ts:111:  recurrenceUntil: z.string().max(10).optional()
outboxWorker.ts:84:  recurrenceUntil: z.string().max(10).optional()
```

Git log confirms `test(06-02)` precedes `feat(06-02)`.

## Known Stubs

None. All test assertions target exact ICS/RRULE strings verified against ical.js 2.2.1 in RESEARCH. No placeholder data.

## Threat Flags

No new threat surface beyond what was planned in T-06-02 / T-06-02b. Both mitigations implemented:

- `z.string().max(10)` on `recurrenceUntil` + `z.number().int().min(1)` on `recurrenceCount` at both route and outbox schema boundaries.
- `assembleRruleString` uses `.replace(/-/g,'')` (digits only) + fixed templates — no raw passthrough to ICS.
- Assembled string passes through `ICAL.Recur.fromString` (parse-rejects malformed RRULE).

## Self-Check: PASSED

| Item                            | Status    |
| ------------------------------- | --------- |
| SUMMARY.md created              | FOUND     |
| RED commit a59455a              | FOUND     |
| GREEN commit d2abb91            | FOUND     |
| 39 tests passing                | CONFIRMED |
| recurrenceUntil in both schemas | CONFIRMED |