feat(ios): complete P2.1 schema versioning and P2.2 combined edge case tests

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.
This commit is contained in:
Matthew Raymer
2025-12-22 12:59:40 +00:00
parent eb1fc9f220
commit 6b5b886951
16 changed files with 2131 additions and 72 deletions

View File

@@ -34,9 +34,9 @@ This document defines the **scope, boundaries, and acceptance criteria** for P2
- Create onboarding reference for contributors
**P2.x — Parity & Resilience Polish**
- Schema versioning strategy (iOS explicit versioning)
- Combined edge case tests (DST + duplicate delivery + cold start)
- Long-tail behavior validation
- P2.1: Schema versioning strategy (iOS explicit versioning)
- P2.2: Combined edge case tests (iOS: DST + duplicate delivery + cold start)
- P2.3: Android combined edge case tests (achieve parity with iOS P2.2)
### What P2 Excludes
@@ -208,19 +208,22 @@ This document defines the **scope, boundaries, and acceptance criteria** for P2
**Scope:**
- Define explicit schema versioning strategy for iOS
- Document migration contract (what changes require version bumps)
- Add version tracking to CoreData model
- Add version tracking to CoreData model (metadata or attribute)
- Ensure Android and iOS versioning strategies are equivalent in practice
- **Clarification:** Schema version is a logical contract, not a forced migration trigger. CoreData auto-migration remains authoritative; version mismatches are logged, not blocked.
**Constraints:**
- Must not break existing data
- Must support forward compatibility
- Must be testable
- Must not interfere with CoreData auto-migration
**Acceptance Criteria:**
- [ ] iOS schema versioning strategy documented
- [ ] Version tracking implemented in CoreData model
- [ ] iOS schema versioning strategy documented (with explicit "logical contract" clarification)
- [ ] Version tracking implemented in CoreData model (metadata or attribute)
- [ ] Migration contract defined (when to bump versions)
- [ ] Tests verify version handling
- [ ] Version check utility added (logs version on init, does not block)
- [ ] Tests verify version handling (if version tracking implemented)
- [ ] Parity matrix updated (schema versioning: ✅ Explicit)
---
@@ -251,32 +254,37 @@ This document defines the **scope, boundaries, and acceptance criteria** for P2
---
#### P2.3: Long-Tail Behavior Validation
#### P2.3: Android Combined Edge Case Tests
**Current State:**
- Core functionality tested
- Edge cases partially tested
- Long-tail scenarios (weeks/months of operation) not validated
- iOS: ✅ Automated combined edge case tests (P2.2 complete)
- Android: ⚠️ Manual emulator scripts only, no automated combined scenarios
**Scope:**
- Document long-tail scenarios that should be validated
- Create test plans (not necessarily automated) for:
- Extended operation (30+ days)
- Multiple DST transitions
- Multiple schema migrations
- High notification volume over time
- Establish validation criteria
- Enable Android test infrastructure (currently disabled in `build.gradle`)
- Create test helpers (in-memory Room database, test data injection)
- Add automated combined edge case tests mirroring iOS P2.2:
- DST boundary + duplicate delivery + cold start
- Rollover + duplicate delivery + cold start
- Schema version + cold start recovery (optional)
- Use CI-compatible testing framework (JUnit + Robolectric or pure unit tests)
**Constraints:**
- May be manual/exploratory initially
- Must be documented and repeatable
- Must not block P2 completion
- Must be CI-compatible (JVM-compatible, no emulator required)
- Must use modern AndroidX testing framework (not deprecated APIs)
- Tests only, no production code changes
- Must not break existing functionality
**Acceptance Criteria:**
- [ ] Long-tail scenarios documented
- [ ] Test plans created (automated or manual)
- [ ] Validation criteria defined
- [ ] Results tracked in progress docs
- [ ] Android test infrastructure enabled and CI-compatible
- [ ] Test helpers created (database factory, data injection)
- [ ] At least 2 combined test scenarios implemented (3 if time permits)
- [ ] Tests verify idempotency in combined scenarios
- [ ] Tests pass in CI (or clearly documented as manual)
- [ ] Parity matrix updated with direct test references
- [ ] Test results logged in `docs/progress/03-TEST-RUNS.md`
**See:** `docs/progress/P2.3-DESIGN.md` for detailed design and execution plan.
---
@@ -284,19 +292,23 @@ This document defines the **scope, boundaries, and acceptance criteria** for P2
### Phase Ordering
**Recommended sequence:**
**Recommended sequence (P2.6/P2.7 already complete):**
1. **P2.7 First** — Document invariants before making changes
- Establishes "what not to break" baseline
- Helps validate P2.6 and P2.x don't violate invariants
1. **P2.1 First (Doc-first approach)**
- Write documentation first
- Then add minimal code (logging/metadata)
- Update parity matrix immediately after
- **Checkpoint:** Run `./ci/run.sh`, update progress docs, only then proceed
2. **P2.6 Second** — Type safety cleanup
- Low risk, high value
- Can be done incrementally (file by file)
2. **P2.2 Second (Tests)**
- Start with 2 scenarios
- Add 3rd only if time/energy allows
- Label tests explicitly as resilience/combined-scenarios
- **Checkpoint:** Run `./ci/run.sh`, update progress docs
3. **P2.x Last** — Parity & resilience polish
- Most complex, may reveal issues
- Benefits from P2.6 type improvements
**Previous phases (complete):**
- **P2.7** — Document invariants before making changes ✅
- **P2.6** — Type safety cleanup ✅
### Incremental Approach