refactor(backend): update event processor

[tyler-dane]

Summary

Refactor Compass recurrence sync from a lifecycle-heavy parser class into explicit planner/executor layers, and document the recurrence model and sync flow more clearly.

Why

The old CompassEventParser was handling too many concerns at once:

• loading DB state
• classifying recurrence transitions
• deciding which persistence path to take
• performing Compass writes
• describing Google side effects

That made the code branch-heavy and stateful. Most methods depended on hidden mutable state set by init(), so the actual inputs and invariants were not obvious from the call sites.

This change separates those responsibilities so each layer answers one question:

• planner: what transition happened and what should happen next?
• executor: what Compass DB mutations should be applied?
• processor: should Google be updated/deleted/created after Compass persistence succeeds?

What changed

Compass sync refactor

• Replaced the stateful parser flow with explicit plan construction in packages/backend/src/event/classes/compass.event.parser.ts
• Added a Compass-only executor in packages/backend/src/event/classes/compass.event.executor.ts
• Updated packages/backend/src/sync/services/sync/compass.sync.processor.ts to:
  • load the current DB event
  • analyze the transition into a CompassOperationPlan
  • apply Compass mutations
  • execute Google effects separately

Explicit plan model

Added internal backend types for the Compass path:

• CompassTransitionContext
• CompassOperationPlan
• CompassApplyResult
• CompassMutation
• GoogleEffectPlan

Notable details:

• new Compass mutation keys use uppercase syntax: CREATE, UPDATE, DELETE, UPDATE_SERIES, RECREATE_SERIES, TRUNCATE_SERIES
• delete-oriented Google effects prefer persisted dbEvent.gEventId before the incoming payload gEventId
• recurrence split behavior is explicit:
  • TRUNCATE_SERIES when only UNTIL changed
  • RECREATE_SERIES when other RRULE semantics changed
  • UPDATE_SERIES when no split is needed

Tests

• Replaced the old parser lifecycle tests with planner-focused unit tests in packages/backend/src/event/classes/compass.event.parser.test.ts
• Added executor unit tests in packages/backend/src/event/classes/compass.event.executor.test.ts
• Extended packages/backend/src/sync/services/sync/tests/compass.sync.processor.test.ts to cover analyze/apply sequencing and Google delete id fallback
• Removed remaining direct setup dependence on the old parser class from packages/backend/src/sync/services/sync/tests/compass.sync.processor.all-event.test.ts

Docs

• Added docs/recurrence-handling.md
• Updated:
  • docs/event-and-task-domain-model.md
  • docs/google-sync-and-websocket-flow.md
  • docs/backend-request-flow.md
  • docs/common-change-recipes.md

Rationale

This refactor reduces hidden state and makes the recurrence path easier to reason about:

• transition analysis is now plain data, not object lifecycle
• Compass DB mutations are centralized in one executor
• Google side effects stay at the processor boundary where external coordination belongs
• recurrence-specific branching is easier to test in isolation
• the sync processor is easier to read because orchestration is explicit instead of spread across parser methods

The main goal was maintainability, not a product behavior change.

Validation

Ran:

yarn test:backend --runTestsByPath packages/backend/src/event/classes/compass.event.parser.test.ts packages/backend/src/event/classes/compass.event.executor.test.ts packages/backend/src/sync/services/sync/__tests__/compass.sync.processor.test.ts --runInBand

Result:

• 3 suites passed
• 16 tests passed

I also observed the existing Compass recurrence-heavy backend integration suites passing during a broader backend run, although a full clean yarn test:backend remains noisy in this environment due to unrelated Jest/Mongo setup issues outside this change.

---

Note

Medium Risk
Refactors core event/recurrence sync orchestration and Google side-effect execution, which could subtly change persistence or sync behavior across many transition paths. Risk is mitigated by new unit tests and largely equivalent transition mapping, but regressions would affect recurring events and Google sync.

Overview
Refactors Compass event write processing from a stateful CompassEventParser lifecycle into an explicit plan/apply/side-effect pipeline: analyzeCompassTransition(...) now builds a CompassOperationPlan, applyCompassPlan(...) executes only Compass DB mutation steps, and CompassSyncProcessor runs Google create/update/delete after successful DB commit.

Adds a new recurrence transition/planning model (series update vs truncate vs recreate), including safeguards like clearing recurrence before Google updates when a series becomes standalone and preferring persisted gEventId for delete operations. Updates backend tests to target the new planner/executor boundaries and adjusts integration tests to create initial series via CompassSyncProcessor.

Documentation is expanded/updated with a new recurrence-handling.md and refreshed backend/google-sync flow docs to match the new architecture, plus removes some debug logging in the Google notification handler.

^{Written by Cursor Bugbot for commit b3725f2. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

[cursor]

Debug console.log left after partial cleanup

Low Severity

This commit removed the label console.log("LATEST CHANGES (from gcal):") but left behind the paired console.log(JSON.stringify(response.data, null, 2)), which dumps the full Google Calendar response payload to stdout. In compass.sync.processor.ts, the analogous pair of console.log statements was fully removed. The inconsistency suggests this line was overlooked during cleanup.