feat(events): replace end_dt column with duration_minutes (#160)

Structural fix for the "end before start" bug class observed on prod 2026-04-29. Bad data became inexpressible at the schema level instead of getting trapped in defensive read-path filters. The hotfix that landed earlier today (94b169f) is reverted by the preceding revert commit; this commit supersedes it cleanly with a proper data-model change. ## Schema (migration 0043) - Add `duration_minutes INTEGER NULLABLE` column on `events`. - CHECK constraint: ``duration_minutes IS NULL OR duration_minutes >= 0``. - Backfill from existing `end_dt`: - end_dt valid (end > start) → duration_minutes = total minutes - end_dt == start → duration_minutes = 0 (zero-duration point) - end_dt NULL or end_dt < start → duration_minutes = NULL (the corrupt prod row collapses cleanly to a point event) - Drop the `end_dt` column. The wire format is preserved — `to_dict()` emits `end_dt` as a derived `start_dt + duration_minutes`. Existing API consumers (Flutter app, web frontend, CalDAV sync) keep receiving the same response shape; they just no longer have a way to PUT a stored `end_dt` that disagrees with `start_dt`. ## Service layer - `Event.end_dt` becomes a `@property`. Setting it would require a setter we deliberately don't define — writes always go through `duration_minutes`. - `_normalize_duration` is the single source-of-truth for input reduction. Accepts (start, end_dt, duration_minutes), returns the canonical `duration_minutes`, raises `ValueError` for negative durations, end-before-start, or end/duration disagreement. - `create_event` and `update_event` accept either `end_dt` or `duration_minutes` for ergonomic compat; both convert via `_normalize_duration`. Update validates the post-update state when the patch includes either. - `list_events` filter is simpler now: a coarse SQL prefilter (`start_dt <= date_to`) plus Python-side refinement using the derived `end_dt`. Avoids Postgres-specific interval arithmetic in the WHERE clause; refinement runs over a per-user result set so there's no scan-cost concern at personal scale. - Recurring-event expansion uses `event.duration_minutes` directly instead of computing `end - start`. No more negative-timedelta hazard. ## CalDAV sync (incoming + outgoing) - `caldav_sync.py` (pull) and `calendar_sync.py` (Radicale upsert) both convert iCal `DTEND` → `duration_minutes` on the way in. Outbound iCal still emits `DTEND` as `start_dt + duration_minutes` via the model's derived property. iCal interop is unchanged. ## Behavioral upgrade for `update_event` Pure end_dt model: moving start past the existing end_dt would either silently corrupt or hard-reject. Duration model: the duration is preserved by default, so moving start slides the effective end forward — which is what users mean when they "move" an event. Explicit clear is still possible via `end_dt=None`. ## Tests `tests/test_events_service.py`: - 6 new `_normalize_duration` unit tests (sugar conversion, zero duration valid as point event, end-before-start rejected, negative duration rejected, inconsistent end+duration rejected, none → None) - New behavioral test: `update_event` preserves duration when only start_dt changes (sliding semantics) - New: clearing `end_dt=None` on update collapses to point event - New: list_events surfaces a point event in the upcoming window - New: list_events excludes a timed event whose effective end has already passed - Existing mock-event helper updated to use `duration_minutes` instead of stored `end_dt`. 44 event-related tests pass; ruff clean. ## Out of scope (separate task) Fable #161 — `find_events_by_query` returning multiple matches and silently picking matches[0]. The exact root cause of how event id=2 got mutated in the first place; orthogonal to the storage model. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-29 14:19:44 -04:00
parent b7e7073425
commit 4c58603009
7 changed files with 517 additions and 90 deletions
@@ -14,7 +14,7 @@ def _make_mock_session():


 def _make_mock_event(id=1, user_id=1, uid="uid-abc", title="Meeting",
-                     caldav_uid="", color=""):
+                     caldav_uid="", color="", duration_minutes=60):
    e = MagicMock()
    e.id = id
    e.user_id = user_id
@@ -23,7 +23,14 @@ def _make_mock_event(id=1, user_id=1, uid="uid-abc", title="Meeting",
    e.caldav_uid = caldav_uid
    e.color = color
    e.start_dt = datetime(2026, 3, 25, 10, 0, tzinfo=timezone.utc)
-    e.end_dt = datetime(2026, 3, 25, 11, 0, tzinfo=timezone.utc)
+    e.duration_minutes = duration_minutes
+    # end_dt is derived; mirror the property's behavior on the mock so
+    # service code that reads `event.end_dt` gets a sensible value.
+    if duration_minutes is None:
+        e.end_dt = None
+    else:
+        from datetime import timedelta
+        e.end_dt = e.start_dt + timedelta(minutes=duration_minutes)
    e.all_day = False
    e.description = ""
    e.location = ""
@@ -32,8 +39,9 @@ def _make_mock_event(id=1, user_id=1, uid="uid-abc", title="Meeting",
    e.to_dict.return_value = {
        "id": id, "uid": uid, "title": title,
        "caldav_uid": caldav_uid, "color": color,
-        "start_dt": datetime(2026, 3, 25, 10, 0, tzinfo=timezone.utc).isoformat(),
-        "end_dt": datetime(2026, 3, 25, 11, 0, tzinfo=timezone.utc).isoformat(),
+        "start_dt": e.start_dt.isoformat(),
+        "end_dt": e.end_dt.isoformat() if e.end_dt else None,
+        "duration_minutes": duration_minutes,
    }
    return e

@@ -124,6 +132,195 @@ async def test_update_event_fires_caldav_push():
        assert mock_task.called


+# ── Duration-model write-side guarantees (Fable #160) ─────────────────────────
+
+
+def test_normalize_duration_from_end_dt():
+    """end_dt sugar converts to a positive minute count anchored on start."""
+    from fabledassistant.services.events import _normalize_duration
+    start = datetime(2026, 5, 1, 8, 0, tzinfo=timezone.utc)
+    end = datetime(2026, 5, 1, 9, 30, tzinfo=timezone.utc)
+    assert _normalize_duration(start_dt=start, end_dt=end, duration_minutes=None) == 90
+
+
+def test_normalize_duration_zero_is_valid_point_event():
+    """end_dt == start_dt → duration 0. The point-with-zero-duration case
+    is rare but legal (e.g. an instant marker); the duration model treats
+    it the same as duration None for display purposes."""
+    from fabledassistant.services.events import _normalize_duration
+    same = datetime(2026, 5, 1, 8, 0, tzinfo=timezone.utc)
+    assert _normalize_duration(start_dt=same, end_dt=same, duration_minutes=None) == 0
+
+
+def test_normalize_duration_rejects_end_before_start():
+    """The exact 2026-04-29 prod failure: end 32 days before start.
+    The duration model makes this inexpressible at the schema level
+    via a CHECK constraint, but write-path callers still get a
+    helpful ValueError if they construct an inconsistent (start, end)
+    pair via the end_dt sugar."""
+    from fabledassistant.services.events import _normalize_duration
+    start = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    end_before = datetime(2026, 3, 30, 12, 0, tzinfo=timezone.utc)
+    with pytest.raises(ValueError, match="at or after start_dt"):
+        _normalize_duration(
+            start_dt=start, end_dt=end_before, duration_minutes=None,
+        )
+
+
+def test_normalize_duration_rejects_negative_duration():
+    """Direct duration_minutes < 0 is rejected. Mirrors the DB CHECK
+    constraint at the service boundary so callers get a clean error
+    rather than a constraint violation from psycopg."""
+    from fabledassistant.services.events import _normalize_duration
+    start = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    with pytest.raises(ValueError, match="must be >= 0"):
+        _normalize_duration(start_dt=start, end_dt=None, duration_minutes=-15)
+
+
+def test_normalize_duration_rejects_inconsistent_end_and_duration():
+    """If a caller passes both end_dt AND duration_minutes that disagree,
+    the inconsistency is surfaced rather than silently picking one."""
+    from fabledassistant.services.events import _normalize_duration
+    start = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    end = datetime(2026, 5, 1, 13, 0, tzinfo=timezone.utc)  # implies 60 min
+    with pytest.raises(ValueError, match="implies 60 minutes"):
+        _normalize_duration(
+            start_dt=start, end_dt=end, duration_minutes=30,
+        )
+
+
+def test_normalize_duration_none_for_open_ended():
+    """Both inputs None → None duration (open-ended event)."""
+    from fabledassistant.services.events import _normalize_duration
+    start = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    assert _normalize_duration(
+        start_dt=start, end_dt=None, duration_minutes=None,
+    ) is None
+
+
+@pytest.mark.asyncio
+async def test_create_event_rejects_end_before_start():
+    """Service-level rejection — same scenario as the prod bug, surfaced
+    cleanly for tool / route callers via ValueError."""
+    from fabledassistant.services.events import create_event
+    start = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    end_before = datetime(2026, 3, 30, 12, 0, tzinfo=timezone.utc)
+    with pytest.raises(ValueError, match="at or after start_dt"):
+        await create_event(
+            user_id=1, title="Bad",
+            start_dt=start, end_dt=end_before,
+        )
+
+
+@pytest.mark.asyncio
+async def test_update_event_preserves_duration_when_only_start_changes():
+    """Sliding semantics: when the user moves an event by changing only
+    start_dt, the existing duration_minutes is preserved as-is. The new
+    effective end_dt slides forward with the start. This is a behavioral
+    upgrade vs. the old end_dt model, where moving start past the
+    stored end made the event 'go backward in time'."""
+    mock_event = _make_mock_event(duration_minutes=60)  # start 10:00, end 11:00
+    mock_session = _make_mock_session()
+    mock_result = MagicMock()
+    mock_result.scalar_one_or_none.return_value = mock_event
+    mock_session.execute = AsyncMock(return_value=mock_result)
+
+    with patch("fabledassistant.services.events.async_session") as mock_cls, \
+         patch("fabledassistant.services.events.asyncio.create_task"):
+        mock_cls.return_value = mock_session
+        from fabledassistant.services.events import update_event
+        # Move start to 12:00; effective end becomes 13:00 automatically.
+        result = await update_event(
+            user_id=1, event_id=1,
+            start_dt=datetime(2026, 3, 25, 12, 0, tzinfo=timezone.utc),
+        )
+    assert result is not None
+    # duration_minutes was NOT touched; mock_event still has 60.
+    assert mock_event.duration_minutes == 60
+
+
+@pytest.mark.asyncio
+async def test_update_event_clearing_end_dt_clears_duration():
+    """Passing end_dt=None on update is the documented way to clear the
+    end (turn a timed event into a point event). The service must
+    translate that into duration_minutes=None, not leave the prior
+    value in place."""
+    mock_event = _make_mock_event(duration_minutes=60)
+    mock_session = _make_mock_session()
+    mock_result = MagicMock()
+    mock_result.scalar_one_or_none.return_value = mock_event
+    mock_session.execute = AsyncMock(return_value=mock_result)
+
+    with patch("fabledassistant.services.events.async_session") as mock_cls, \
+         patch("fabledassistant.services.events.asyncio.create_task"):
+        mock_cls.return_value = mock_session
+        from fabledassistant.services.events import update_event
+        await update_event(user_id=1, event_id=1, end_dt=None)
+    assert mock_event.duration_minutes is None
+
+
+@pytest.mark.asyncio
+async def test_list_events_includes_point_event_in_window():
+    """A point event (duration_minutes=None) surfaces when its start
+    is in the window. Replaces the prior 'corrupt end_dt' regression
+    test — the duration model can't represent that state, but the
+    same code path is exercised here for point events."""
+    mock_event = _make_mock_event(duration_minutes=None)
+    # Point event in the upcoming window
+    mock_event.start_dt = datetime(2026, 5, 1, 12, 0, tzinfo=timezone.utc)
+    mock_event.end_dt = None
+    mock_event.to_dict.return_value = {
+        "id": 1, "title": "Point",
+        "start_dt": mock_event.start_dt.isoformat(),
+        "end_dt": None,
+        "duration_minutes": None,
+    }
+    mock_session = _make_mock_session()
+    mock_result = MagicMock()
+    mock_result.scalars.return_value.all.return_value = [mock_event]
+    mock_session.execute = AsyncMock(return_value=mock_result)
+
+    with patch("fabledassistant.services.events.async_session") as mock_cls:
+        mock_cls.return_value = mock_session
+        from fabledassistant.services.events import list_events
+        results = await list_events(
+            user_id=1,
+            date_from=datetime(2026, 4, 29, tzinfo=timezone.utc),
+            date_to=datetime(2026, 5, 27, tzinfo=timezone.utc),
+        )
+        assert len(results) == 1
+        assert results[0]["id"] == 1
+
+
+@pytest.mark.asyncio
+async def test_list_events_excludes_timed_event_that_already_ended():
+    """A timed event whose start + duration is before the window must
+    NOT surface. Verifies the Python-side refinement actually works
+    against the coarse SQL prefilter."""
+    mock_event = _make_mock_event(duration_minutes=60)
+    # Start 4/20 12:00, end 4/20 13:00; window is 4/29 → 5/27 — fully past.
+    mock_event.start_dt = datetime(2026, 4, 20, 12, 0, tzinfo=timezone.utc)
+    mock_event.end_dt = datetime(2026, 4, 20, 13, 0, tzinfo=timezone.utc)
+    mock_event.to_dict.return_value = {
+        "id": 1, "start_dt": mock_event.start_dt.isoformat(),
+        "end_dt": mock_event.end_dt.isoformat(), "duration_minutes": 60,
+    }
+    mock_session = _make_mock_session()
+    mock_result = MagicMock()
+    mock_result.scalars.return_value.all.return_value = [mock_event]
+    mock_session.execute = AsyncMock(return_value=mock_result)
+
+    with patch("fabledassistant.services.events.async_session") as mock_cls:
+        mock_cls.return_value = mock_session
+        from fabledassistant.services.events import list_events
+        results = await list_events(
+            user_id=1,
+            date_from=datetime(2026, 4, 29, tzinfo=timezone.utc),
+            date_to=datetime(2026, 5, 27, tzinfo=timezone.utc),
+        )
+        assert results == []
+
+
@pytest.mark.asyncio
 async def test_tools_calendar_always_available():
    """Calendar tools must appear in get_tools_for_user even without CalDAV."""