Telematics Core Migration MVP (Implementation-Time BDD)

Feature Narrative

• Story: As Accounts, Operations, and Support users, we need one canonical telematics freshness and health contract so stale/no-data devices are discoverable quickly and values stay consistent across Manage pages.
• Trigger: EventBridge-triggered workspace poll cycles execute inside bf-manage-core, websocket ingress updates flow from bf-telematics into the same core command handler, and read APIs compute request-time health and issues.
• Outcomes:
• 5-minute target cadence with staggered workspace starts.
• Core owns all scheduled polling tasks.
• One canonical snapshot for values and last update received.
• One shared core handler for websocket and scheduled poll updates.
• Request-time health states (healthy, delayed, stale, configured-no-data) with actionable stale/no-data reporting.
• Observable lifecycle traces, KPI visibility, and reversible per-workspace cutover controls.

Scenario Inventory

• Execute staggered 5-minute workspace poll cycles.
• Persist canonical snapshot and event history atomically for accepted payloads.
• Reject invalid canonical payloads that fail workspace/device identity validation.
• Keep telematics values and freshness consistent across Manage read surfaces.
• Compute request-time health state from persisted snapshot, ingest history, and device configuration.
• Return stale/no-data lists with reason and recency context for Accounts follow-up.
• Roll back read/poll ownership to legacy mode without destructive data changes.

Phase 2 BDD Backlog

• Reject synchronized scheduling configurations before activation.
• Add explicit configured-no-data grace-breach timing scenario separate from classification outline.
• Return deterministic health-report empty-state contract for no stale/no-data devices.
• Emit traceable poll-cycle lifecycle records across telematics ingress and core ingest.
• Expose workspace KPI indicators for cycle success, delay patterns, and update coverage.
• Progress workspace cutover from shadow to core read ownership with parity-gate checks.

Gherkin Scenarios

@behavior @implementation @telematics
Feature: Telematics core migration with freshness and health visibility
  Fleet users can trust telematics freshness and diagnose stale/no-data devices from one canonical core contract.

  Rule: Workspace polling runs on a staggered 5-minute target cadence
    Background:
      Given active workspaces are configured for telematics polling

    Scenario: Execute staggered 5-minute workspace poll cycles
      When the scheduler triggers a polling window
      Then each active workspace receives one poll cycle attempt within the 5-minute target cadence
      And workspace start times are staggered rather than aligned to one synchronized start instant
      And the scheduled poll path does not call `bf-telematics`

  Rule: Canonical snapshot persistence is the single source of telematics truth
    Background:
      Given canonical handoff payloads are submitted from websocket ingress or core-owned poll execution into core command handling

    Scenario: Persist snapshot and event history atomically for accepted updates
      When a payload passes identity and schema validation
      Then one canonical snapshot for that configured workspace/device/vehicle is upserted
      And event history for the accepted update is appended in the same transaction
      And the snapshot includes current values and last update received timestamp

    Scenario: Use one core handler for websocket and scheduled poll updates
      Given websocket ingress and scheduled polling produce the same canonical update payload shape
      When either path submits an update into core
      Then core applies the same validation and persistence flow
      And the accepted update is observable through the same canonical snapshot and event history contract

    Scenario: Reject invalid payload identity mapping
      Given a payload has unresolved or conflicting workspace/device identity
      When core command validation runs
      Then the payload is rejected without mutating snapshot state
      And the rejection outcome is observable for diagnostics

    Scenario: Keep telematics values consistent across Manage read surfaces
      Given a canonical snapshot has been updated for a configured device
      When multiple Manage pages read telematics freshness/value data
      Then each page reads from the canonical snapshot/health contract
      And returned values and freshness timestamps are consistent within one refresh cycle

  Rule: Health and issue classification is computed at request time
    Background:
      Given workspace policy defaults are stale threshold 15 minutes and configured-no-data grace 60 minutes
      And device configuration and latest accepted updates are persisted in core

    Scenario Outline: Classify request-time health state deterministically
      Given a configured device has freshness age <freshness_age_minutes> minutes
      And the device has accepted update history <has_history>
      When a health report is requested
      Then the device health state is <expected_state>
      And the response includes freshness age and reason context
      Examples:
        | freshness_age_minutes | has_history | expected_state      |
        | 3                     | yes         | healthy             |
        | 9                     | yes         | delayed             |
        | 22                    | yes         | stale               |
        | 65                    | no          | configured-no-data  |

  Rule: Health reporting is actionable for Accounts and Support workflows
    Background:
      Given workspace health data is available from request-time query calculation

    Scenario: Return stale/no-data lists with follow-up context
      When Accounts requests a workspace telematics health report
      Then the response includes stale and configured-no-data device lists
      And each listed device includes reason and recency context for outreach

  Rule: Cutover toggles provide reversible per-workspace migration control
    Background:
      Given workspace cutover controls include device registry source, poll owner, read owner, and provider mode

    Scenario: Roll back workspace to legacy ownership safely
      Given a workspace is using core read ownership
      When rollback is triggered by defined canary guardrails
      Then read owner and poll owner are set to legacy mode
      And no destructive data migration is required to restore service continuity

Coverage Review

• Criterion intent: Run per-workspace poll cycles on 5-minute target cadence with staggered starts.
  • Scenario titles: Execute staggered 5-minute workspace poll cycles.
  • Status: covered
• Criterion intent: Persist one canonical telematics snapshot with last update received per configured device/vehicle.
  • Scenario titles: Persist snapshot and event history atomically for accepted updates.
  • Status: covered
• Criterion intent: Provide workspace health reporting with stale/no-data discoverability.
  • Scenario titles: Classify request-time health state deterministically; Return stale/no-data lists with follow-up context.
  • Status: covered
• Criterion intent: Ensure all Manage pages read telematics freshness/value from canonical core contract.
  • Scenario titles: Keep telematics values consistent across Manage read surfaces.
  • Status: covered
• Criterion intent: Expose workspace-level indicators and traceability for collection reliability.
  • Scenario titles: Emit traceable cycle lifecycle records; Expose workspace telematics KPI indicators.
  • Status: deferred
• Criterion intent: Enforce transitional ownership boundary (bf-telematics ingress, bf-manage-core command/query).
  • Scenario titles: Execute staggered 5-minute workspace poll cycles; Persist snapshot and event history atomically for accepted updates; Use one core handler for websocket and scheduled poll updates.
  • Status: covered
• Criterion intent: Keep request-time health/issues calculation until event-bus projections are introduced.
  • Scenario titles: Classify request-time health state deterministically; Return stale/no-data lists with follow-up context.
  • Status: covered
• Criterion intent: NFR freshness reliability target (95% within 5 minutes) and request-time latency budgets.
  • Scenario titles: Execute staggered 5-minute workspace poll cycles; Expose workspace telematics KPI indicators.
  • Status: deferred

Gaps / Open Questions

• NFR thresholds are defined, but explicit executable pass/fail thresholds for first-wave load and query-latency budgets are still open (OQ-005).
• Notification strategy for stale/no-data is unresolved (OQ-003): passive report-only vs active notifications.
• First-wave Manage page scope for canonical cutover is unresolved (OQ-004), which affects final UI e2e scope.
• Post-MVP event bus/projection readiness gates remain unresolved (OQ-006).
• Permission-role behavior is not explicitly specified in the telematics spec for health-report access control.

Automation Target Plan

• bf-manage-web Cypress e2e candidate grouping: extend existing cypress/e2e/baseline/ with telematics-focused specs (for example cypress/e2e/baseline/telematics-health.cy.ts) and reuse page-level patterns from overview.cy.ts and vehicles-page.cy.ts.
• bf-manage-web runnable commands discovered from package.json:
• npm run e2e:baseline for baseline-group execution.
• npm run e2e:all or npm run e2e:ci-all for broader regression.
• bf-manage-core pytest targets for backend behavior:
• Existing telematics suites under test/telematics_mvp/ (test_scheduler.py, test_service.py, test_router.py, test_polling_tasks.py, test_runtime.py) for scheduler, ingest, query, and toggle behavior.
• Existing compatibility coverage under test/telematics/test_telematics.py for legacy path non-regression.
• Suggested backend additions:
• test/telematics_mvp/test_health_report_contract.py for stale/no-data payload and deterministic empty-state.
• test/telematics_mvp/test_cutover_toggle_rollbacks.py for shadow/canary/core transitions and rollback safety.
• Optional adapter: pytest-bdd can be introduced later if the team wants executable Gherkin binding; not required for initial implementation.