Feature/esp scheduler v2

[zekageri]

Summary

This PR promotes esp-scheduler v2 as the new primary architecture on main.

The motivation is to replace the old v1 task-per-job async design with a scheduler model that is more ESP32-friendly, easier to reason about, and safer around lifecycle and shutdown:

• one central SchedulerCore
• one optional background SchedulerService task
• executor-based async dispatch
• shared manual/background semantics
• v1 compatibility through ESPSchedulerV1Compat

Related issues: none linked in this PR body.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Documentation update
• Build/CI

Details

This PR is not a cosmetic refactor of v1. It introduces a materially different execution architecture for esp-scheduler.

What changed:

• Added explicit SchedulerMode, DispatchPolicy, and OverlapPolicy
• Added explicit lifecycle via begin() / end()
• Switched mutating/query APIs to SchedulerResult<T>
• Split schedule math into ScheduleSpec / ScheduleCalculator
• Reworked async execution around:
  • InlineExecutor
  • WorkerPoolExecutor
  • DedicatedTaskExecutor
  • optional built-in ESPWorker backend
• Added background command/event serialization so background mode no longer depends on tick()
• Added ESPSchedulerV1Compat for migration
• Added scheduler-owned metadata allocation paths and PSRAM-aware runtime/task-stack handling
• Added direct-indexed job lookup/completion and explicit pending-schedule bookkeeping in the core
• Updated CI to run compile verification on pushes, with separate v2 API, examples, and test-sketch coverage
• Updated README, changelog, examples, and tests to reflect v2 as the primary public story

Why:

• lower RAM overhead than task-per-job async execution
• better ownership and lifecycle behavior
• real background scheduling without mandatory tick()
• cleaner executor integration, including ESPWorker
• a clearer migration path for v1 users

Reviewer context / tradeoffs:

• The worker-pool executor is now the default async model for ESP32
• Dedicated-task execution still exists, but only as an advanced opt-in / compatibility path
• Shutdown is significantly safer than v1, but still uses force-delete fallback after timeout for stuck worker/service tasks; this is documented as best-effort behavior, not graceful draining
• v1 compatibility is intentionally additive and thin; the primary API surface is now v2

Testing

• Builds locally
• Unit tests added/updated
• Tested on target hardware/device (if applicable)

Tests and validation performed:

• Updated Unity/device test coverage for:
  • overlap policies
  • lifecycle begin/end behavior
  • slot reuse
  • stale completion handling
  • invalid-clock scheduling behavior
  • v1 compatibility cleanup behavior
• Added compile-only v2 API sketch coverage
• Ran git diff --check

Local build status:

• Full local PlatformIO compile could not be completed from this environment because the local PlatformIO installation is broken outside the repo:
  • Python environment missing pip
  • installed tool-esptoolpy package missing manifest
• CI is intended to be the final compile gate for this PR

Commands attempted:

• git diff --check
• pio ci examples/v2_api_compile ... (blocked by local PlatformIO environment issue)
• pio ci test/test_esp_scheduler ... (blocked by local PlatformIO environment issue)

Compatibility / Breaking Changes

This is a breaking architectural change.

Behavior/API changes:

• ESPScheduler v2 is now the primary API surface
• Async scheduling no longer defaults to one FreeRTOS task per job
• Background mode no longer requires tick()
• Public mutating/query APIs use SchedulerResult<T>
• Lifecycle is explicit via begin() / end()
• Async executor selection is now policy/config based
• ESPSchedulerV1Compat exists for migration, but it is not the main API

Migration guidance:

• Existing users should either:
  • migrate to v2 ESPScheduler, or
  • temporarily use ESPSchedulerV1Compat
• Old inline/worker-task style usage maps roughly to:
  • v1 Inline -> DispatchPolicy::Inline
  • v1 WorkerTask -> DispatchPolicy::Async
• Per-job task config should use the dedicated-task path only when truly needed

Risks and Mitigations

Risks:

• This is a large architectural change and touches runtime, lifecycle, CI, examples, and docs
• There may still be integration fallout that only appears in full matrix CI or on hardware
• Shutdown remains best-effort for stuck worker/service tasks
• v1 compatibility may preserve shape but not every old performance/lifecycle assumption

Mitigations:

• Added/expanded test coverage around overlap, lifecycle, slot reuse, and stale events
• Added compile-only v2 API example to catch public API regressions
• Kept a dedicated v1 compatibility wrapper for migration
• Documented shutdown tradeoffs explicitly in README
• CI is expanded to cover v2 API compilation, examples, and test-sketch builds on push

Checklist

• Code follows project style and conventions
• All tests pass locally
• Documentation updated (README, examples, comments)
• No secrets, credentials, or sensitive data committed
• Linked issue(s) and relevant context provided

Environment

• Toolchain/SDK versions:
  • PlatformIO Core 6.1.19
  • Intended CI targets include PlatformIO + Arduino CLI ESP32 builds
• OS and version:
  • Linux
• Other relevant environment details:
  • Local gh CLI was not available in the implementation environment
  • Local PlatformIO environment was not healthy enough for trustworthy compile verification