feat: add requiresDeviceIdle constraint + opportunistic-dispatch docs

[happycodelucky]

What

Adds a new cross-platform work constraint, WorkConstraints.requiresDeviceIdle, and documents the library's opportunistic-dispatch contract — both in response to the question "how do we support 'run this when the OS gives the app space', and what is the Android equivalent of iOS background fetch?"

Two deliverables:

1. requiresDeviceIdle: Boolean = false — "only dispatch when the device is idle." It was previously parked as a v2 gap in the WorkConstraints KDoc; it now ships.
2. docs/concepts/opportunistic-dispatch.md — names the contract that already governs every platform (intervals are floors, not promises; the OS picks the moment) and pre-answers the recurring "why didn't my background task run on time" confusions.

Why

The "do this when the OS gives you space" behaviour was already the library's only mode — BGTaskScheduler / WorkManager / NSBackgroundActivityScheduler all dispatch opportunistically. What was missing was (a) a documented name for that contract so callers stop reading interval as a wall-clock promise, and (b) the Android-idle constraint, which is the concrete "idle?" analogue the iOS background-fetch model implies.

Platform behaviour (the honest table)

requiresDeviceIdle follows the same advisory-constraint template as requiresCharging:

Platform	Behaviour	Mechanism
Android	Enforced	Constraints.Builder.setRequiresDeviceIdle(true) → JobScheduler (Doze / maintenance windows). Surfaces as PendingPredicate.RequiresDeviceIdle via scheduled().
iOS	Advisory (no-op)	BGProcessingTaskRequest has no idle property (only requiresExternalPower / requiresNetworkConnectivity); the system already prefers idle moments. One-time log.w, mirroring the existing NetworkRequirement.Unmetered warning.
macOS	Advisory (no-op)	NSBackgroundActivityScheduler has no idle primitive; already biases idle via qualityOfService = .background. Silent-with-comment.
JVM	Advisory (no-op)	No OS idle concept. Silent-with-comment.

Reviewer notes

• @Serializable compatibility: new field has a default (= false) and is appended (existing field order unchanged) — serialization/binary compatible.
• Inspector parity: PendingPredicate.RequiresDeviceIdle + Android WorkInfo read-back were wired at every touch-point that RequiresCharging already occupies (field → AndroidConstraintsMapper → AndroidScheduledTaskMapper predicate + snapshot data class → PendingPredicate), to avoid the duplicate-drift trap this repo has hit before.
• macOS/JVM deliberately log nothing. Those files already treat requiresCharging as silent-with-a-doc-note; I matched the local convention rather than inventing a log they don't have. iOS does log because its applyConstraints already logs for Unmetered.
• No WorkerContext / clock changes. This adds no timing logic — N-011 (no wall-clock in scheduler math) and N-012 (no WorkerContext singleton proxy) are not touched.
• minInterval / last-run throttling was considered and descoped by the owner this session — opportunistic dispatch already floors execution frequency, so a throttle would be redundant machinery. Captured in LESSONS D-025 so it isn't re-proposed.
• Docs are strict-mode clean: the new concept page deep-links into a new network-required.md#require-the-device-to-be-idle anchor and is wired into mkdocs.yml nav; mkdocs build --strict + the repo's docs:check both pass.

Verification

• ./gradlew check — PASS (82 tasks; all unit tests across JVM/Android/macOS/iOS-sim; no ktlint/detekt failures)
• ./gradlew :backgrounder:linkDebugFrameworkIosArm64 — PASS (iOS framework links clean)
• mise run docs:check + mkdocs build --strict — PASS

🤖 Generated with Claude Code