feat(monitor): instrumentation + inspector + :background-monitor module

[happycodelucky]

Summary

Implements the full instrumentation + inspector + optional monitor module from the plan in /Users/paulbates/.claude/plans/in-backgrounders-i-d-like-humble-eclipse.md. Four commits, each a self-contained wave.

Existing BackgrounderEventListener consumers see no behaviour change — the four v1-shape callbacks (onScheduled / onStarted / onCompleted / onCancelled) still fire identically. Everything new layers alongside without breaking anything.

What's in each commit

Wave 1 — MonitorEvent model + emitter foundation (a03e1d4)

• MonitorEvent — sealed interface with 10 cases: Scheduled, ScheduleReplaced, Cancelled, WorkStarted, WorkCompleted, AttemptDeferred, Skipped, AttemptFailed, RetryScheduled, LibraryError.
• Four helper sealed types (CancelSource, DeferralReason, SkipReason, AttemptFailureReason) — top-level, not nested inside MonitorEvent, because SKIE bridges nested-inside-sealed unreliably (LESSONS D-004).
• MonitorEventEmitter — internal single-point fan-out. Synchronous dispatch to the v1 listener for the four v1-shape events only; tryEmit to a SharedFlow(replay=0, extraBufferCapacity=64, DROP_OLDEST) for all 10. Non-suspending so a slow collector cannot pin scheduler dispatch (CLAUDE.md §3).
• Backgrounder.events(): SharedFlow<MonitorEvent> — public, SKIE-bridged to AsyncSequence<MonitorEvent> for Swift.
• MonitorEventEmitterTest (4 cases) — green on macOS / iOS sim / Android host.

Wave 2 — platform emit-site swaps + 6 richer events (f2f5983)

Every platform scheduler now routes through MonitorEventEmitter. Builders thread one emitter instance through scheduler + bridge + dispatcher.

• iOS (BGTaskBackedScheduler / IOSCoroutineBridge / IOSPeriodicDispatcher):
  • Scheduled / ScheduleReplaced (Replace policy displacing an active task) / Cancelled(User) from BGTaskBackedScheduler.
  • LibraryError on BGTaskScheduler.submit failure (previously Kermit-only).
  • WorkStarted with expectedAt read from IOSStateStore.nextRunEpochMs.
  • Skipped(NotRegistered) on no-factory; AttemptFailed(FactoryThrew) / AttemptFailed(WorkerThrew) / AttemptFailed(ExpiredByOS) on the matching paths.
  • AttemptDeferred(ReachabilityTimeout) from both the bridge and the periodic dispatcher when the network gate times out.
  • RetryScheduled on one-shot retry resubmits and periodic backoff overrides; emitted after WorkCompleted so observers see "attempt finished → retry queued" in natural order.
• macOS (NSBackgroundActivityBackedScheduler): mirror of iOS, including RetryScheduled from handleOneShotRetry. Cancel emit calls hoisted outside the synchronized blocks — emit-outside-the-lock is the convention going forward.
• Android (WorkManagerScheduler / RegistryDispatchWorker): Scheduled / ScheduleReplaced / Cancelled(User) from the scheduler; ephemeral-not-ready bail → Skipped(EphemeralExpired); input deser failure → LibraryError; no-factory → Skipped(NotRegistered); factory/worker throw → AttemptFailed(FactoryThrew|WorkerThrew); RetryScheduled with delay = ZERO / nextRunHint = null (WorkManager owns the backoff curve internally).

Only test fixture needing an update was IOSPeriodicDispatcherTest, which now wraps its RecordingListener in MonitorEventEmitter(events) before passing it to the dispatcher.

Wave 3 — inspector additions (6a031d9)

Closes the inspector half of the plan — operators can ask the Backgrounder who owns each task id, what's blocking each scheduled task from running, and is the environment configured correctly.

• Backgrounder.registeredTaskIds(): Set<TaskId> — delegates to WorkerRegistry.registeredIds().
• Backgrounder.registeredFactories(): List<FactoryDescriptor> — new WorkerRegistry.factoryDescriptors(). FactoryDescriptor is a sealed interface with PerId (one closure per id) and Bulk (a BackgroundWorkerFactory object owning many ids) cases. Bulk descriptors carry the new optional BackgroundWorkerFactory.factoryId for module attribution; default null, no existing implementer needs updating.
• Backgrounder.diagnostics(): PlatformDiagnostics — new PlatformDiagnostic sealed interface with MissingInfoPlistEntry(taskId) (iOS), BackgroundRefreshDisabled (iOS, reserved — see below), WorkManagerNotInitialized (Android), and the common RegistryNotSealed. Backed by expect/actual platformDiagnostics(...).
  • iOS actual reads BGTaskSchedulerPermittedIdentifiers from NSBundle.mainBundle and emits MissingInfoPlistEntry per registered id absent from the array. BackgroundRefreshDisabled is defined but not emitted yet — UIApplication.backgroundRefreshStatus requires the main thread, and diagnostics() is a sync call. A future suspend fun variant can hop to main to read it.
  • Android actual reads WorkManager.isInitialized() via AndroidBackgrounderInternals (the side-table now keeps an Application ref keyed by WorkerRegistry).
  • macOS actual returns only the RegistryNotSealed finding when applicable — NSBackgroundActivityScheduler is in-process, no OS-level config to check.
• ScheduledTask.pendingPredicates: List<PendingPredicate> (default empty) — NetworkRequired, RequiresCharging, WaitingForBackoff(until), WaitingForEarliestBeginDate(at). Per-platform population:
  • iOS (IOSScheduledTaskQuery): reads networkRequired and nextRunEpochMs from IOSStateStore. RequiresCharging reserved (not currently persisted; v2 follow-up gated on a schema bump).
  • Android (AndroidScheduledTaskMapper): reads WorkInfo.constraints (network type → NetworkRequired, requiresCharging() → RequiresCharging) plus the existing nextScheduleTimeMillis → backoff/earliestBegin distinction. WorkInfoView gains an optional constraintsView projection.
  • macOS: WaitingForBackoff(null) when attempt > 0. Constraints aren't retained after the NSBackgroundActivityScheduler is built.
• InspectorApiTest (6 cases) covering descriptor ordering, factoryId surface, mixed-registration ordering, defaults, and PlatformDiagnostics.isHealthy semantics.

Wave 4 — :background-monitor module + docs + LESSONS (b09776d)

New optional sibling Gradle module published as com.happycodelucky.backgrounder:background-monitor. KMP + Android targets matching the core, ARM-only per CLAUDE.md §1. SKIE intentionally omitted — pure-Swift consumers continue to use the core's existing Backgrounder.xcframework. api(project(":backgrounder")) so consumers transitively see MonitorEvent, ScheduledTask, etc.

Three public types in commonMain:

• Monitor — single-method suspend fun onEvent(event) interface; SKIE bridges as a Swift protocol with an async requirement.
• AttachedMonitor — handle returned by attachMonitor(scope, monitor), with idempotent detach() and isActive.
• SnapshotPoller(backgrounder, interval) — runs scheduled() + diagnostics() on a poll loop and exposes the latest results as StateFlow<List<ScheduledTask>?> + StateFlow<PlatformDiagnostics>. Errors per iteration are swallowed; the next tick retries.

attachMonitor(scope, monitor) is an extension function on Backgrounder defined in :background-monitor so the core stays free of any Monitor reference — a circular module dependency would otherwise arise (mirrors how Ktor wires plugins). Multiple monitors can attach to one Backgrounder; each runs its own collector coroutine.

MonitorAttachTest (5 cases) exercises delivery, detach, idempotency, multi-subscriber fan-out, and isActive semantics. Subscriber-count await is the load-bearing detail — without it, tryEmit on a replay=0 flow drops events emitted before the launched collector registers.

Docs:

• docs/recipes/inspect.md — "v2: Reactive observe()" section replaced with a real "Reactive event stream" example pointing at events(), plus paragraphs introducing registeredFactories() and diagnostics().
• docs/recipes/monitor.md — new code-first walk-through of the 10 MonitorEvent cases, the optional :background-monitor attach API, SnapshotPoller usage, and a "What can go wrong" section matching the docs voice.
• mkdocs.yml nav updated; docs/check.py invariants hold.

LESSONS.md D-019 documents the tryEmit-only contract on MonitorEventEmitter — the load-bearing reason a slow events() collector cannot pin scheduler dispatch (CLAUDE.md §3, the per-task Mutex on iOS).

Test plan

• :backgrounder:macosArm64Test — full existing suite + MonitorEventEmitterTest (4) + InspectorApiTest (6) green.
• :backgrounder:iosSimulatorArm64Test — full existing suite green; IOSPeriodicDispatcherTest updated.
• :backgrounder:testAndroidHostTest — full existing suite green.
• :background-monitor:macosArm64Test / iosSimulatorArm64Test / testAndroidHostTest — MonitorAttachTest (5) green on all three.
• Reviewer to confirm the wider event model (10 cases) covers the use cases the user enumerated, and the inspector surface (registeredFactories / diagnostics / pendingPredicates) is the right shape for the dashboards they want to build downstream.

🤖 Generated with Claude Code