Skip to main content

​
Purpose

This page documents the live execution paths in the current app implementation. Use it when you need to answer questions like:
  • “What runs on app startup?”
  • “What exactly happens when a task is completed?”
  • “How do check-ins write events?”
  • “Where do replayed events affect mana computation?”
This page is implementation-facing. It reflects current code paths under app/lib.

​
Startup flow

Startup does two phases:
  1. Boot and app wiring in main.dart
  2. First today mana compute triggered by screen providers

​
Complete task occurrence flow

When the user taps Complete on the Tasks screen, the write path is transactional and event-backed.

​
Completion payload contract

taskOccurrenceCompleted currently carries:
  • occurrence/task identity
  • due/completed timestamps
  • manaCostAtCompletion
  • axisFactorAtCompletion
  • baselineCostAtCompletion
  • completedLocalDay
The engine uses this event stream to compute spent today and reduce remaining mana deterministically.

​
Save check-in flow

Check-in writes are canonicalized to one row per local day and emit two events atomically.

​
Why two events?

  • checkInRecorded preserves explicit check-in submission data.
  • dayTypeSet provides replay-friendly day opportunity weight context.
Both are written in the same transaction as the check-in row, so replay cannot see partial state.

​
Task edit flow with recovery-weight emission

Task edits always emit taskEdited.
They emit taskRecoveryWeightUpdated only when recovery fields were touched and values actually changed.

​
Replay consumption during compute

Historical events are sorted by occurredAt then id, then reduced into deterministic learning state.

​
Determinism and safety invariants

  • All replay-affecting signals come from append-only event history.
  • Event ordering is stable (occurredAt, then id).
  • Check-in and completion writes use DB transactions for row+event atomicity.
  • Recompute is idempotent for a fixed input set and algorithm version.

​
Code anchors

  • app/lib/main.dart
  • app/lib/ui/core/design/typography.dart
  • app/lib/ui/core/providers/mana_day_view_providers.dart
  • app/lib/domain/application/mana/compute_mana_day.dart
  • app/lib/ui/tasks/widgets/tasks_screen.dart
  • app/lib/domain/application/tasks/complete_task_occurrence.dart
  • app/lib/data/repositories/drift_task_repository.dart
  • app/lib/domain/application/check_ins/save_check_in.dart
  • app/lib/data/repositories/drift_check_in_repository.dart
  • app/lib/domain/mana/engine/historical_learning_state_reducer.dart
  • app/lib/domain/mana/engine/composed_mana_engine.dart