Behavior on SAFER Documentation

CPM Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Scope

This document defines the runtime CPM pipeline from accelerometer samples to prediction consumption.

Canonical Flow

App.tsx starts startActivityService() on mount and calls stopActivityService() on cleanup.
activityService starts expo-sensors accelerometer streaming at ~30 Hz.
Sensor samples are buffered in memory (src/sensors/accelerometer.ts), converted from g to m/s^2, timestamped from the native sensor event, and pruned to the last ~75 seconds.
activityService treats a CPM window as ready only when it spans nearly 60 seconds, allowing one configured sensor interval of tolerance.
Every 60 seconds, activityService reads the most recent ready window and calls computeCpmFrom60s(...) in src/model/inferenceActivity.ts, which consumes the collected 30 Hz window directly.
When CPM computation succeeds, one row is written to cpm_history in SQLite through src/db/cpmDb.ts.
Callers such as predictionHeatRisk and PredictionCoreTempCard consume getActivityCpm40Average() from activityService.

Readiness Contract (`getActivityCpm40Average`)

Window: last 40 minutes.
Minimum history: at least 35 rows.
Freshness: latest row must be <= 2 minutes old.
Return: average CPM when ready, otherwise null.

Supporting References

Schema: schemas/cpm-history.md
Diagram: ../diagrams/activity-cpm-pipeline.mmd

Invariants

Model behavior lives in src/model/inferenceActivity.ts; orchestration should stay in activityService.
The model consumes the collected 30 Hz window directly; there is no separate 60 Hz downsampling stage.
Each successful minute tick produces at most one persisted CPM row.
Storage shape, retention, and query ordering live in the schema doc.

Daily Work Area

Mon, 01 Jan 0001 00:00:00 +0000

Daily Work-Area Pre-Cache Behavior

Scope

This document defines the once-per-day work-area screen flow that pre-warms weather cache entries from a farmer-selected circular work area.

Canonical Flow

When the Home/work-area screen becomes focused, the app checks whether the local calendar day has already shown the work-area pre-cache modal.
If the day has not shown the modal, a blocking full-screen modal asks the farmer to define today’s work area by tapping a map center point, selecting an address suggestion, or finding a typed address, then choosing a radius.
The modal seeds from today’s saved area first; otherwise it pre-fills from the most recent prior work area within the fallback window; otherwise it opens centered on Sacramento and may recenter once to current device location if foreground permission succeeds before the farmer edits.
Save today’s area persists one DailyWorkAreaCircle for the current local day and marks the day handled.
Use previous work day is available only when a saved work area exists within the previous 7 local calendar days; it does not create a new circle for today, but it does mark today handled after pre-cache runs.
A top-right Close action is available only when no recent fallback exists; it dismisses the already-shown daily prompt without warming weather cells.
The chosen circle is expanded by one weather-cache cell (2.5 km) for safety, converted into deduped cache-cell center points, and passed to precacheWeatherForLocations(...).
precacheWeatherForLocations(...) warms one forecast cell per unique location by fetching and storing a fresh 24-hour forecast horizon for that cell.
Manual reopen/edit from Home uses the same modal and re-runs pre-cache when the farmer saves a new circle later that day.

Persistence Rules

One circle is stored per local day key (YYYY-MM-DD in device-local time).
Prompt-shown state is stored separately from daily circles so app launch alone cannot suppress the work-area prompt before the farmer reaches the Home/work-area screen.
Fallback lookup only considers the most recent prior saved work day within 7 days.
Daily pre-cache treats the current hour as part of the horizon when the upstream NDFD response includes it; otherwise it accepts the next 24 contiguous forecast hours.

Invariants

Daily work-area pre-caching does not change prediction weather sourcing; foreground and background predictions still use live device location.
Pre-cache writes must go through precacheWeatherForLocations(...), which uses a dedicated fetch/store warming path rather than the single-hour getWeatherPointCached(...) lookup contract.
The modal is blocking only for the first focused Home/work-area screen visit of the local day where the modal has not already appeared; later edits are user-initiated from Home and are dismissible.

Weather Caching Behavior

Mon, 01 Jan 0001 00:00:00 +0000

Scope

This document defines the runtime lookup policy for getWeatherPointCached(...) in src/services/weatherService.ts. Daily work-area pre-warming uses the same weather service module but follows its own dedicated 24-hour horizon warming path through precacheWeatherForLocations(...).

Behavior on SAFER Documentation

CPM Pipeline

Scope

Canonical Flow

Readiness Contract (getActivityCpm40Average)

Supporting References

Invariants

Daily Work Area

Daily Work-Area Pre-Cache Behavior

Scope

Canonical Flow

Persistence Rules

Invariants

Weather Caching Behavior

Scope

Readiness Contract (`getActivityCpm40Average`)