Created src/core/metrics.ts with:
- PerformanceMetric interface
- MetricsCollector interface
- InMemoryMetricsCollector implementation
Updated src/core/index.ts to export metrics.
Note: Web stub (src/web.ts) doesn't need timing instrumentation since it throws immediately. Real instrumentation will be in platform implementations (P3.1-C).
Verification:
- TypeScript compiles ✅
- Core purity check passes ✅
- No new dependencies ✅
Created detailed, file-by-file, function-by-function execution plan for P3.
Includes:
- Exact files to modify
- Exact functions to instrument
- Exact event codes to add
- Exact JSDoc patterns
- Exact commands to run
- Batch-by-batch execution plan
Ready for Cursor execution after approval.
Created P3-DESIGN.md with scope for:
- P3.1: Performance optimization & metrics
- P3.2: Enhanced observability
- P3.3: Developer experience improvements
- P3.4: Documentation polish
Updated baseline tag reference to v1.0.11-p2.3-p1.5b-complete
P3 focuses on polish, performance, and developer experience while maintaining all established invariants.
Moved legacy iOS test harness from ios/App/ to test-apps/ios-app-legacy/
Rationale:
- Test harness should not be in published package tree
- Active test app remains at test-apps/ios-test-app/
- Legacy test harness preserved for reference
Verification:
- Confirmed ios/App no longer appears in npm pack --dry-run
- Build passes successfully
- Package structure cleaner
Progress Docs:
- Updated 00-STATUS.md: marked P1.5b complete
- Updated 01-CHANGELOG-WORK.md: added P1.5b completion entry
Updated 03-TEST-RUNS.md with actual test execution results:
- All 3 combined edge case tests passing (100% success rate)
- Test execution command documented
- Robolectric configuration fix noted
P2.1: iOS Schema Versioning Strategy
- Added SCHEMA_VERSION constant and checkSchemaVersion() method in PersistenceController
- Version stored in NSPersistentStore metadata (observability contract, not migration gate)
- CoreData auto-migration remains authoritative; version mismatches logged, not blocked
- Documentation added to ios/Plugin/README.md with migration contract
P2.2: Combined Edge Case Tests
- Added 3 resilience test scenarios to DailyNotificationRecoveryTests.swift:
- test_combined_dst_boundary_duplicate_delivery_cold_start()
- test_combined_rollover_duplicate_delivery_cold_start()
- test_combined_schema_version_cold_start_recovery()
- All tests labeled with @resilience @combined-scenarios comments
- Tests verify idempotency and correctness under combined stressors
P2.3: Android Combined Tests Design
- Created P2.3-DESIGN.md with scope, invariants, and acceptance criteria
- Created P2.3-IMPLEMENTATION-CHECKLIST.md with step-by-step execution plan
- Design ready for implementation to achieve parity with iOS P2.2
Documentation Updates
- Fixed parity matrix: iOS invalid data handling now correctly shows "✅ Recovery tested" with test references
- Updated progress docs (00-STATUS.md, 01-CHANGELOG-WORK.md, 03-TEST-RUNS.md, 04-PARITY-MATRIX.md)
- Updated P2-DESIGN.md to reflect P2.3 scope (Android combined tests)
- Updated SYSTEM_INVARIANTS.md baseline tag references
Baseline Tag
- Created and pushed v1.0.11-p2-complete tag
- Tag represents P2.x completion (schema versioning + combined resilience tests)
All invariants preserved. CI passes. Tests runnable via xcodebuild on macOS.
Exclude temporary archive files (*.zip, *.gz) from version control.
These are typically temporary extraction artifacts and should not be
committed.
Author: Matthew Raymer
Add three test buttons (Empty, Invalid, Negative) below the "Test Notification"
button to test invalid time format handling. Each button attempts to schedule
a notification with invalid values: empty string, "25:00" (invalid hour), and
"-1:30" (negative time).
Improve TEST 3 error detection in test-phase1.sh by:
- Making grep case-insensitive to catch ERROR/invalid patterns
- Adding DNP-* error prefix patterns for plugin error logs
- Documenting that Capacitor bridge errors (⚡️ logs) appear in Xcode console
but not in system logs captured by xcrun simctl
The script was using 'local' keyword outside of function scope,
which caused "local: can only be used in a function" error when
running test-phase2.sh. Removed 'local' from three variable
assignments (device_id and logs) at script top level, as 'local'
is only valid inside functions in bash/zsh.
- Fix getNextNotificationTime() to find earliest scheduled notification
instead of using first request (pendingNotificationRequests doesn't
guarantee order)
- Add comprehensive logging for rollover tracking with DNP-ROLLOVER
prefix for Xcode console filtering
- Reset all notifications and rollover state when scheduling new
notification via scheduleDailyNotification() to ensure clean test
state
- Fix userInfo scope error in handleNotificationDelivery error handler
- Update test app UI to refresh status every 5-10 seconds and
immediately after notification delivery to reflect rollover changes
- Add console logging in UI to debug getNotificationStatus() results
This ensures the UI correctly displays the next notification time after
rollover completes, and test notifications start with a clean slate.
Fixed multiple issues in iOS test script and added logging for test compatibility:
Test Script Fixes:
- Fixed get_simulator_id() to correctly extract UUID from booted devices
- Fixed get_app_logs() to use log show (historical) instead of log stream (live) to avoid hanging
- Improved check_plugin_configured() with multiple detection methods (app container, app listing, data directory)
- Added ensure_plugin_configured() function matching Android pattern for consistent user interaction flow
- Fixed integer comparison error in booted device check (removed newlines from count)
- Removed 'local' keyword from variables in main script body (local can only be used in functions)
- Fixed APP_BUNDLE_ID to match actual bundle identifier
Pending Notification Detection:
- Improved get_pending_notifications() to parse pendingCount from plugin logs
- Added direct log query without restrictive predicate to catch plugin logs
- Added multiple fallback methods for detecting pending count
Plugin Logging Enhancement:
- Added explicit pendingCount logging in DailyNotificationScheduler after scheduling
- Uses both NSLog() and print() to ensure logs appear in system logs and Xcode console
- Matches Android's alarm count logging pattern for test script compatibility
This resolves script crashes and enables reliable detection of pending notifications
for automated testing.
Fixed Swift compilation errors preventing iOS build:
- Added explicit self capture [self] in closures in DailyNotificationReactivationManager
- Removed invalid BGTaskScheduler.shared.registeredTaskIdentifiers API call
- Fixed initialization order in DailyNotificationModel (verifyEntities after container init)
Added missing configureNativeFetcher method to iOS plugin:
- Implemented method matching Android functionality
- Stores configuration in UserDefaults for persistence
- Registered method in pluginMethods array
- Supports both jwtToken and jwtSecret parameters for compatibility
This resolves the runtime error "configureNativeFetcher is not a function"
that was preventing the test app from configuring the plugin.
Implement comprehensive data access layer for Core Data entities:
- Add NotificationContentDAO, NotificationDeliveryDAO, and NotificationConfigDAO
with full CRUD operations and query helpers
- Add DailyNotificationDataConversions utility for type conversions
(Date ↔ Int64, Int ↔ Int32, JSON, optional strings)
- Update PersistenceController with entity verification and migration policies
- Add comprehensive unit tests for all DAO classes and data conversions
- Update Core Data model with NotificationContent, NotificationDelivery,
and NotificationConfig entities (relationships and indexes)
- Integrate ReactivationManager into DailyNotificationPlugin.load()
DAO Features:
- Create/Insert methods with dictionary support
- Read/Query methods with predicates (by timesafariDid, notificationType,
scheduledTime range, deliveryStatus, etc.)
- Update methods (touch, updateDeliveryStatus, recordUserInteraction)
- Delete methods (by ID, by key, delete all)
- Relationship management (NotificationContent ↔ NotificationDelivery)
- Cascade delete support
Test Coverage:
- 328 lines: DailyNotificationDataConversionsTests (time, numeric, string, JSON)
- 490 lines: NotificationContentDAOTests (CRUD, queries, updates)
- 415 lines: NotificationDeliveryDAOTests (CRUD, relationships, cascade delete)
- 412 lines: NotificationConfigDAOTests (CRUD, queries, active filtering)
All tests use in-memory Core Data stack for isolation and speed.
Completes sections 4.4, 4.5, and 6.0 of iOS implementation checklist.
Adds complete iOS documentation suite to support iOS implementation
parity with Android features. Includes implementation directives,
recovery scenario mappings, database migration guide, troubleshooting
guide, and test scripts.
New Documentation:
- iOS Implementation Directive: Phase-based implementation guide
mirroring Android structure with iOS-specific considerations
- iOS Recovery Scenario Mapping: Maps Android recovery scenarios
to iOS equivalents with detection logic comparisons
- iOS Core Data Migration Guide: Complete Room → Core Data entity
mappings with implementation checklist for missing entities
- iOS Troubleshooting Guide: Common issues, debugging techniques,
and error code reference
Enhanced Documentation:
- API.md: Added iOS-only methods (permissions, background tasks,
pending notifications), platform differences table, and iOS-specific
error types. Updated version to 2.3.0.
Test Infrastructure:
- iOS test scripts for Phase 1 (cold start), Phase 2 (termination),
and Phase 3 (boot recovery) testing scenarios
All documentation addresses gaps identified in iOS Implementation
Documentation Review and provides foundation for iOS recovery feature
implementation (currently pending).
Note: iOS recovery features (ReactivationManager, scenario detection)
are NOT yet implemented. Documentation is ready to guide implementation.
Boot recovery runs twice on Android (both LOCKED_BOOT_COMPLETED and
BOOT_COMPLETED fire). The first run marks missed alarms (missed=1), while
the second run only reschedules future alarms (missed=0).
TEST 2 was incorrectly extracting the last entry (missed=0) instead of
the first entry (missed=1), causing false test failures.
Changes:
- Extract first missed count using head -n1 instead of tail -n1
- Add comment explaining why first entry is needed
- Test now correctly validates missed alarm detection
Fixes test validation for past alarm detection during boot recovery.
Changes COLD_START scenario detection log from DEBUG to INFO so it's
visible in test output when recovery runs. This improves testability
and debugging visibility for scenario detection.
The log message was already informative but hidden at DEBUG level,
making it difficult to verify scenario detection in test runs.
Implements force stop scenario detection and comprehensive alarm recovery.
Adds scenario differentiation (FORCE_STOP, BOOT, COLD_START, NONE) to route
recovery logic appropriately.
Changes:
- Add RecoveryScenario enum and detectScenario() method
- Add performForceStopRecovery() for force stop scenario
- Add alarmsExist() helper to check AlarmManager state
- Update isBootRecovery() to ignore flags < 1 second old (emulator quirk fix)
- Update BootReceiver to only set boot flag for actual boot events
- Add test script step to clear boot flag before testing
- Fix compiler warnings (remove unused parameters)
Fixes false BOOT detection when alarms are cleared after force stop.
Boot flag age validation prevents emulator quirks from triggering BOOT
scenario during app launch.
Implements: Plugin Requirements §3.1.4 - Force Stop Recovery
Implements automated testing for TEST 4 (Invalid Data Handling) to verify
recovery gracefully handles invalid database entries without crashing.
Changes:
- Add injectInvalidTestData plugin method for injecting invalid test data
(empty schedule IDs, null nextRunAt, empty notification IDs)
- Make test app debuggable to enable direct database access
- Enhance test-phase1.sh with automated database injection and verification:
* Detect debuggable app status (check for DEBUGGABLE flag)
* Inject invalid data via direct SQL (schedules and notifications)
* Handle WAL mode with checkpoint
* Verify data injection success
* Trigger recovery and check logs for "Skipping invalid" messages
* Report pass/fail/inconclusive results
Fixes database constraint issues discovered during testing:
- Include jitterMs and backoffPolicy in schedule inserts
- Include priority, vibration_enabled, sound_enabled in notification inserts
Test results: ✅ PASSED
- Invalid data successfully injected
- Cold start recovery correctly skips invalid entries
- Recovery completes without crashing
- Boot recovery processes invalid data (follow-up improvement needed)
This enables automated verification that recovery handles corrupted or
invalid database entries gracefully, preventing crashes in production.
Fix duplicate alarm bug where updating schedule time created multiple
schedules in database, violating "one notification per day" contract.
Plugin Changes:
- Use stable scheduleId "daily_notification" instead of timestamp-based IDs
- Delete all existing notification schedules before creating new one
- Cancel alarms in AlarmManager before database deletion
- Add detailed logging for cleanup operations
- Make scheduleDailyReminder delegate to scheduleDailyNotification
Test Harness Changes:
- Make TEST 2 fail when alarm count > 1 after schedule update
- Make TEST 2 fail when alarm count > 1 after recovery
- Add clear failure messages explaining "one per day" violation
- Add final verdict section with detailed failure summary
Results:
- Before: 2-3 alarms, 2 schedules in DB, "Pending: 2" in UI
- After: 1 alarm, 1 schedule in DB, "Pending: 1" in UI
- TEST 2 now correctly passes with proper validation
This ensures that updating schedule time maintains exactly one alarm
per day, preventing duplicate notifications and database bloat.
Add automatic app state reset for TEST 1 to ensure clean starting state when
lingering alarms from TEST 0 are detected. Create PHASE1_TEST1_GOLDEN.md with
actual values from successful run.
TEST 1 Auto-Reset:
- Detect lingering plugin alarms before TEST 1 starts
- Automatically uninstall/reinstall app to clear alarms
- Verify clean state (0 alarms) before proceeding
- Gracefully skip TEST 1 if clean state cannot be achieved
- Take failure screenshots when reset fails
- Wrap all TEST 1 steps in conditional to skip on reset failure
Documentation:
- Create PHASE1_TEST1_GOLDEN.md with actual values from passing run
- Document auto-reset behavior in golden run steps
- Add cross-references between TEST 0 and TEST 1 golden docs
- Include actual timestamps, scheduleIds, and recovery metrics
This ensures TEST 1 always starts from a known clean state, making test
results reliable and reproducible. The golden doc serves as a baseline for
comparing future TEST 1 runs.
Fix alarm counting to correctly parse dumpsys output where app ID and
action appear on different lines. Add screenshot capture for test
diagnostics and create golden run documentation.
Test Harness Improvements:
- Fix get_plugin_alarm_count() to track app ID and action separately
across alarm block lines (fixes false 0-count bug)
- Add show_plugin_alarms_compact() to display complete alarm blocks
- Add wait_for_stable_plugin_alarm_count() polling helper to reduce
race condition false negatives
- Add take_screenshot() and take_failure_screenshot() helpers for
automatic test state capture
- Integrate screenshots into TEST 0 at key checkpoints
- Update TEST 0 messaging to handle race conditions gracefully
- Add screenshots/ to .gitignore
Documentation:
- Create PHASE1_TEST0_GOLDEN.md with actual values from successful run
- Document expected script output, UI state, dumpsys shape, and logcat
patterns
- Include pass/fail checklist for future test runs
This fixes the issue where alarm counting always returned 0 because the
AWK logic required app ID and action on the same line, but dumpsys
output has them on separate lines (header line has app ID, tag line
has action).
Centralize all notification alarm scheduling through NotifyReceiver.scheduleExactNotification()
with idempotence checks to prevent duplicate alarms. Implement one-alarm policy using
setAlarmClock() only. Fix test harness alarm counting to deduplicate by Alarm handle.
Plugin Changes:
- Add ScheduleSource enum to track scheduling paths (INITIAL_SETUP, ROLLOVER_ON_FIRE, etc.)
- Add DB-level idempotence check before scheduling (prevents logical duplicates)
- Add explicit alarm cancellation before scheduling (safety net)
- Implement one-alarm policy: use setAlarmClock() only, no setExact* fallbacks for same event
- Add deep logging for all AlarmManager calls (variant, requestCode, pendingIntentHash)
- Update all rollover paths (DailyNotificationReceiver, DailyNotificationWorker) to use
centralized function with ROLLOVER_ON_FIRE source
- Add @JvmStatic annotation to scheduleExactNotification for Java interop
Test Harness Changes:
- Fix get_plugin_alarm_count() to deduplicate by Alarm handle (prevents double-counting
same alarm in main list and "Next wake from idle" section)
- Update TEST 0 messaging: treat 0 alarms as race condition (inconclusive, not failure)
- Make post-rollover check the authoritative assertion point (only fails on >1 or 0 alarms)
- Remove redundant "Found 0 alarms - test may not be accurate" messages
This fixes the duplicate alarm bug where two distinct AlarmManager entries were created
for the same daily notification, violating the "one notification per day" contract.
Remove the 'List Alarms' button and alarm list display functionality
from the Android test app UI. This feature was added for testing but
is no longer needed as alarm verification is handled by the test scripts.
Removed:
- '📋 List Alarms' button
- alarmListContainer div and alarm list display
- loadAlarmList() JavaScript function
- getSchedulesWithStatus() API call usage
The getSchedulesWithStatus() plugin method remains available for
programmatic use if needed in the future.
Fix ReactivationManager to use correct DAO method names and entity
constructor for NotificationContentEntity:
- Change getById() to getNotificationById()
- Change insert() to insertNotification()
- Update NotificationContentEntity construction to use Java class
constructor with positional parameters
- Set entity fields using Java property syntax after construction
This fixes compilation errors introduced when switching to Java-based
NotificationContentEntity class.
Extract common helper functions from test-phase1.sh, test-phase2.sh,
and test-phase3.sh into a shared library (alarm-test-lib.sh) to reduce
code duplication and improve maintainability.
Changes:
- Create alarm-test-lib.sh with shared configuration, UI helpers, ADB
helpers, log parsing, and test selection logic
- Refactor all three phase test scripts to source the shared library
- Remove ~200 lines of duplicated code across the three scripts
- Preserve all existing behavior, CLI arguments, and test semantics
- Maintain Phase 1 compatibility (print_* functions, VERIFY_FIRE flag)
- Update all adb references to use $ADB_BIN variable
- Standardize alarm counting to use shared count_alarms() function
Benefits:
- Single source of truth for shared helpers
- Easier maintenance (fix once, benefits all scripts)
- Consistent behavior across all test phases
- No functional changes to test execution or results
Adds ability to list alarms with AlarmManager status in web interface.
Changes:
- Add getSchedulesWithStatus() method to DailyNotificationPlugin
- Add ScheduleWithStatus TypeScript interface with isActuallyScheduled flag
- Add alarm list UI to android-test-app with status indicators
Backend:
- getSchedulesWithStatus() returns schedules with AlarmManager verification
- Checks isAlarmScheduled() for each notify schedule with nextRunAt
- Returns isActuallyScheduled boolean flag for each schedule
TypeScript:
- New ScheduleWithStatus interface extending Schedule
- Method signature with JSDoc and usage examples
UI:
- New "📋 List Alarms" button in test app
- Color-coded alarm cards (green=scheduled, orange=not scheduled)
- Shows schedule ID, next run time, pattern, and AlarmManager status
- Useful for debugging recovery scenarios and verifying alarm state
Use case:
- Verify which alarms are in database vs actually scheduled
- Debug Phase 1/2/3 recovery scenarios
- Visual confirmation of alarm state after app launch/boot
Related:
- Enhances: android-test-app for Phase 1-3 testing
- Supports: Recovery verification and debugging
Implements boot-time recovery that restores alarms after device reboot,
matching Phase 3 directive and test suite expectations.
Changes:
- Add ReactivationManager.runBootRecovery() companion method
- Update BootReceiver to delegate to ReactivationManager
- Handle past alarms: mark as missed, schedule next occurrence
- Handle future alarms: reschedule immediately
- Use DNP-REACTIVATION tag for all boot recovery logs
- Log summary: "Boot recovery complete: missed=X, rescheduled=Y, verified=0, errors=Z"
- Record history with scenario=BOOT
Recovery behavior:
- Loads all schedules from database on boot
- Detects past vs future scheduled times
- Marks missed notifications for past alarms
- Reschedules all alarms (past and future)
- Completes within 2-second timeout (non-blocking)
- Handles empty DB gracefully (logs "BOOT: No schedules found")
Implementation details:
- Uses companion object method for static access from BootReceiver
- Helper methods for schedule calculation, missed marking, rescheduling
- Error handling: non-fatal, continues processing other schedules
- History recording with boot_recovery kind and scenario=BOOT
Related:
- Implements: android-implementation-directive-phase3.md
- Requirements: docs/alarms/03-plugin-requirements.md §3.1.1
- Testing: docs/alarms/PHASE3-EMULATOR-TESTING.md
- Verification: docs/alarms/PHASE3-VERIFICATION.md
Adds documentation and test harness for Phase 2 (Force Stop Detection & Recovery).
Changes:
- Add PHASE2-EMULATOR-TESTING.md with detailed test procedures
- Add PHASE2-VERIFICATION.md with test matrix and verification template
- Add test-phase2.sh automated test harness
Test harness features:
- 3 test cases: force stop with cleared alarms, intact alarms, empty DB
- Automatic force stop simulation via adb
- Log parsing for scenario detection and recovery results
- UI prompts for plugin configuration and scheduling
Related:
- Directive: android-implementation-directive-phase2.md
- Requirements: docs/alarms/03-plugin-requirements.md §3.1.4
- Testing: docs/alarms/PHASE2-EMULATOR-TESTING.md
- Verification: docs/alarms/PHASE2-VERIFICATION.md
Remove duplicate status matrix from Section 3.3 and consolidate to Section 11
as single source of truth. Fix all section number references throughout
documentation.
Changes:
- Remove duplicate status matrix table from Section 3.3
- Update all references from "Section 3.3" and "Section 10" to "Section 11"
- Fix phase directive paths to use consistent ../ prefix format
- Fix P1 path typo (missing "directive" in filename)
- Update Doc C status in matrix to reflect completion
- Remove duplicate text in Doc B baseline scenarios
- Remove self-referencing links in Doc B
All status matrix references now point to Section 11, eliminating confusion
about which matrix is authoritative.
