feat(docs): complete P2.6 type safety cleanup and P2.7 system invariants
P2.6: Type Safety Cleanup - Replaced 'any' return types in vite-plugin.ts with concrete types (UserConfig, transform return type) - Documented TypeScript mixin 'any[]' exception in PlatformServiceMixin.ts - Audit confirmed: zero 'any' in codebase except documented TS mixin limitation - All external boundaries use 'unknown', all data payloads use 'Record<string, unknown>' P2.7: System Invariants Documentation - Created SYSTEM_INVARIANTS.md documenting all 6 enforced invariants - Added to docs/00-INDEX.md under Policy & Contracts section - Each invariant includes: What, Why, How, Where Progress Docs Updates: - Updated 00-STATUS.md: marked P2.6/P2.7 complete, added type safety invariant note - Updated 01-CHANGELOG-WORK.md: added 2025-12-22 entries for P2.6/P2.7 - Updated 03-TEST-RUNS.md: added P2.6 type safety audit test run - Updated P2-DESIGN.md: marked P2.6 acceptance criteria complete - Updated SYSTEM_INVARIANTS.md: added Type Safety Notes section Baseline Tag: - Created v1.0.11-p0-p1.4-p1.5-p2.6-p2.7-complete TypeScript compilation: ✅ PASSES Build: ✅ PASSES CI: ✅ All checks pass
This commit is contained in:
Matthew Raymer
430
docs/progress/P2-DESIGN.md
Normal file
430
docs/progress/P2-DESIGN.md
Normal file
@@ -0,0 +1,430 @@
|
||||
# P2 Design: Parity & Resilience Polish
|
||||
|
||||
**Purpose:** Defines scope, boundaries, and acceptance criteria for P2 work before implementation begins.
|
||||
**Owner:** Development Team
|
||||
**Last Updated:** 2025-12-22
|
||||
**Status:** design-only (no implementation)
|
||||
**Baseline:** `v1.0.11-p0-p1.4-complete`
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the **scope, boundaries, and acceptance criteria** for P2 work **before any implementation begins**. It ensures P2:
|
||||
|
||||
- Does not violate established invariants
|
||||
- Has clear "done" criteria
|
||||
- Can be executed incrementally
|
||||
- Maintains the stability achieved in P0/P1.4/P1.5
|
||||
|
||||
---
|
||||
|
||||
## P2 Scope Definition
|
||||
|
||||
### What P2 Includes
|
||||
|
||||
**P2.6 — Type Safety Cleanup**
|
||||
- Replace TypeScript `any` with `unknown`/generics where appropriate
|
||||
- Improve type safety without changing runtime behavior
|
||||
- Maintain backward compatibility
|
||||
|
||||
**P2.7 — System Invariants Documentation**
|
||||
- Document all enforced invariants
|
||||
- Explain "why" behind policy-as-code
|
||||
- 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
|
||||
|
||||
### What P2 Excludes
|
||||
|
||||
- **No new features** — P2 is polish, not expansion
|
||||
- **No architectural changes** — Core structure remains unchanged
|
||||
- **No breaking API changes** — Backward compatibility required
|
||||
- **No new platforms** — Focus on existing iOS/Android/Web
|
||||
- **No new dependencies** — Minimize external additions
|
||||
|
||||
---
|
||||
|
||||
## Invariants That Must Not Be Violated
|
||||
|
||||
### 1. Packaging Invariants (P0)
|
||||
|
||||
**Enforced by:** `verify.sh` → `check_package()`
|
||||
|
||||
- `npm pack --dry-run` must not contain forbidden files:
|
||||
- `xcuserdata/`, `*.xcuserstate`, `DerivedData/`
|
||||
- `ios/App/`, `.DS_Store`, `*.swp`, `*.swo`, `*.orig`, `*.rej`
|
||||
- `package.json.files` whitelist must remain authoritative
|
||||
- `.npmignore` is secondary (belt-and-suspenders only)
|
||||
|
||||
**P2 Constraint:** Any P2 changes must not introduce new forbidden file patterns or break packaging checks.
|
||||
|
||||
---
|
||||
|
||||
### 2. Core Module Purity (P1.4)
|
||||
|
||||
**Enforced by:** `verify.sh` → `check_core_source()` + `check_core_artifacts()`
|
||||
|
||||
- `src/core/` must not import:
|
||||
- Node builtins (`fs`, `path`, `os`, `child_process`, etc.)
|
||||
- Platform-specific modules (`@capacitor/*`, `react`, `capacitor`)
|
||||
- `package.json.exports['./core']` must exist and point to valid artifacts
|
||||
- Core types must remain platform-agnostic
|
||||
|
||||
**P2 Constraint:** P2.6 type safety work must not introduce platform dependencies into core.
|
||||
|
||||
---
|
||||
|
||||
### 3. CI Authority (P0)
|
||||
|
||||
**Enforced by:** `ci/README.md` (policy-as-code contract)
|
||||
|
||||
- `./ci/run.sh` is the **only** supported CI entrypoint
|
||||
- All gates (release, merge, automation) must call `./ci/run.sh`
|
||||
- `npm run build` must not be called directly in gates
|
||||
|
||||
**P2 Constraint:** P2 work must not bypass CI or create alternative entrypoints.
|
||||
|
||||
---
|
||||
|
||||
### 4. Export Correctness (P0)
|
||||
|
||||
**Enforced by:** `verify.sh` → `check_build()`
|
||||
|
||||
- `package.json.exports["./web"]` paths must match actual build artifacts
|
||||
- `package.json.exports["./core"]` paths must match actual build artifacts
|
||||
- All exported paths must exist after build
|
||||
|
||||
**P2 Constraint:** P2.6 type changes must not break export paths or artifact generation.
|
||||
|
||||
---
|
||||
|
||||
### 5. Documentation Structure (P1.5)
|
||||
|
||||
**Enforced by:** `docs/00-INDEX.md` (index-first rule)
|
||||
|
||||
- New docs must be linked from `docs/00-INDEX.md` or placed in `_archive/`/`_reference/`
|
||||
- Progress docs are authoritative (no drift)
|
||||
- Archive structure standardized (`docs/_archive/`)
|
||||
|
||||
**P2 Constraint:** P2.7 SYSTEM_INVARIANTS.md must be added to index and follow drift guard format.
|
||||
|
||||
---
|
||||
|
||||
### 6. Baseline Tag Integrity
|
||||
|
||||
**Baseline:** `v1.0.11-p0-p1.4-complete`
|
||||
|
||||
- This tag represents a known-good architectural baseline
|
||||
- All invariants enforced in tooling
|
||||
- Documentation structure established
|
||||
|
||||
**P2 Constraint:** P2 work must not invalidate the baseline or require rollback to it.
|
||||
|
||||
---
|
||||
|
||||
## P2 Work Items (Detailed)
|
||||
|
||||
### P2.6: Type Safety Cleanup
|
||||
|
||||
**Goal:** Replace `any` with `unknown`/generics where appropriate, improving type safety without changing runtime behavior.
|
||||
|
||||
**Scope:**
|
||||
- Audit all `any` usages in `src/` (excluding test files initially)
|
||||
- Categorize by risk:
|
||||
- **Low risk:** Type guards with `unknown`, generic constraints
|
||||
- **Medium risk:** API boundaries, error handling
|
||||
- **High risk:** Core module types, public interfaces
|
||||
- Prioritize: Core module → Public interfaces → Internal code
|
||||
|
||||
**Constraints:**
|
||||
- Must not break existing TypeScript compilation
|
||||
- Must not change runtime behavior
|
||||
- Must maintain backward compatibility
|
||||
- Must pass all existing tests
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [x] Zero `any` in `src/core/` (except where truly necessary, documented)
|
||||
- [x] Public interfaces (`src/definitions.ts`, `src/index.ts`) use `unknown`/generics
|
||||
- [x] All changes pass `npm run build` and `npm test`
|
||||
- [x] No new type errors introduced
|
||||
- [x] Existing tests pass unchanged
|
||||
|
||||
**Exit Criteria:**
|
||||
- [x] Type safety improved measurably (grep `any` count reduced to zero except documented exception)
|
||||
- [x] No runtime behavior changes
|
||||
- [x] All CI checks pass
|
||||
- [x] Documentation updated (changelog, status, test runs)
|
||||
|
||||
**Status:** ✅ Complete (2025-12-22)
|
||||
|
||||
---
|
||||
|
||||
### P2.7: System Invariants Documentation
|
||||
|
||||
**Goal:** Create a single authoritative document that names, explains, and references all enforced invariants.
|
||||
|
||||
**Scope:**
|
||||
- Document all invariants listed in "Invariants That Must Not Be Violated" above
|
||||
- For each invariant:
|
||||
- **What:** Clear statement of the invariant
|
||||
- **Why:** Rationale (why it exists, what it prevents)
|
||||
- **How:** How it's enforced (tooling, process, documentation)
|
||||
- **Where:** References to enforcing code/docs
|
||||
- Include onboarding guidance for new contributors
|
||||
|
||||
**Constraints:**
|
||||
- Must reference existing policy-as-code (not duplicate it)
|
||||
- Must be added to `docs/00-INDEX.md` under "Policy & Contracts"
|
||||
- Must follow drift guard format (Purpose, Owner, Last Updated, Status)
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] `docs/SYSTEM_INVARIANTS.md` created with all invariants documented
|
||||
- [ ] Each invariant has: What, Why, How, Where
|
||||
- [ ] Document added to `docs/00-INDEX.md`
|
||||
- [ ] Drift guard header present
|
||||
- [ ] References to enforcing code are accurate and up-to-date
|
||||
|
||||
**Exit Criteria:**
|
||||
- Single source of truth for all invariants
|
||||
- New contributors can understand "what not to break"
|
||||
- Document is discoverable via index
|
||||
|
||||
---
|
||||
|
||||
### P2.x: Parity & Resilience Polish
|
||||
|
||||
**Goal:** Address remaining parity gaps and add resilience tests for edge cases.
|
||||
|
||||
#### P2.1: Schema Versioning Strategy
|
||||
|
||||
**Current State:**
|
||||
- Android: Room migrations (explicit versioning)
|
||||
- iOS: CoreData auto-migration (implicit, may need explicit strategy)
|
||||
|
||||
**Scope:**
|
||||
- Define explicit schema versioning strategy for iOS
|
||||
- Document migration contract (what changes require version bumps)
|
||||
- Add version tracking to CoreData model
|
||||
- Ensure Android and iOS versioning strategies are equivalent in practice
|
||||
|
||||
**Constraints:**
|
||||
- Must not break existing data
|
||||
- Must support forward compatibility
|
||||
- Must be testable
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] iOS schema versioning strategy documented
|
||||
- [ ] Version tracking implemented in CoreData model
|
||||
- [ ] Migration contract defined (when to bump versions)
|
||||
- [ ] Tests verify version handling
|
||||
- [ ] Parity matrix updated (schema versioning: ✅ Explicit)
|
||||
|
||||
---
|
||||
|
||||
#### P2.2: Combined Edge Case Tests
|
||||
|
||||
**Current State:**
|
||||
- Individual edge cases tested (DST, duplicate delivery, cold start)
|
||||
- Combined scenarios not explicitly tested
|
||||
|
||||
**Scope:**
|
||||
- Create test scenarios that combine multiple edge cases:
|
||||
- DST boundary + duplicate delivery + cold start
|
||||
- Rollover + migration + recovery
|
||||
- Network failure + rollover + cold start
|
||||
- Ensure idempotency and correctness in combined scenarios
|
||||
|
||||
**Constraints:**
|
||||
- Must not duplicate existing test coverage unnecessarily
|
||||
- Must be runnable in CI (or clearly marked as manual)
|
||||
- Must be deterministic
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] At least 3 combined edge case test scenarios
|
||||
- [ ] Tests verify idempotency in combined scenarios
|
||||
- [ ] Tests pass in CI or are clearly documented as manual
|
||||
- [ ] Test results logged in `docs/progress/03-TEST-RUNS.md`
|
||||
|
||||
---
|
||||
|
||||
#### P2.3: Long-Tail Behavior Validation
|
||||
|
||||
**Current State:**
|
||||
- Core functionality tested
|
||||
- Edge cases partially tested
|
||||
- Long-tail scenarios (weeks/months of operation) not validated
|
||||
|
||||
**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
|
||||
|
||||
**Constraints:**
|
||||
- May be manual/exploratory initially
|
||||
- Must be documented and repeatable
|
||||
- Must not block P2 completion
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Long-tail scenarios documented
|
||||
- [ ] Test plans created (automated or manual)
|
||||
- [ ] Validation criteria defined
|
||||
- [ ] Results tracked in progress docs
|
||||
|
||||
---
|
||||
|
||||
## P2 Execution Strategy
|
||||
|
||||
### Phase Ordering
|
||||
|
||||
**Recommended sequence:**
|
||||
|
||||
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
|
||||
|
||||
2. **P2.6 Second** — Type safety cleanup
|
||||
- Low risk, high value
|
||||
- Can be done incrementally (file by file)
|
||||
|
||||
3. **P2.x Last** — Parity & resilience polish
|
||||
- Most complex, may reveal issues
|
||||
- Benefits from P2.6 type improvements
|
||||
|
||||
### Incremental Approach
|
||||
|
||||
- Each P2 item can be completed independently
|
||||
- No dependencies between P2.6, P2.7, and P2.x
|
||||
- Each item has its own acceptance criteria
|
||||
- Can pause/resume at any item boundary
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- **P2.6:** Existing tests must pass unchanged
|
||||
- **P2.7:** Documentation review (no code changes)
|
||||
- **P2.x:** New tests required, existing tests must pass
|
||||
|
||||
---
|
||||
|
||||
## P2 "Done" Criteria
|
||||
|
||||
### Overall P2 Completion
|
||||
|
||||
P2 is complete when:
|
||||
|
||||
1. **All P2 items completed** (P2.6, P2.7, P2.x)
|
||||
2. **All invariants preserved** (verified by CI)
|
||||
3. **All acceptance criteria met** (per item)
|
||||
4. **Documentation updated** (progress docs, index, changelog)
|
||||
5. **Baseline tag created** (if desired: `v1.0.11-p2-complete`)
|
||||
|
||||
### Individual Item Completion
|
||||
|
||||
Each P2 item is complete when:
|
||||
|
||||
- [ ] Acceptance criteria met
|
||||
- [ ] CI passes (`./ci/run.sh`)
|
||||
- [ ] No invariant violations
|
||||
- [ ] Documentation updated (if applicable)
|
||||
- [ ] Progress docs updated
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Risk: Breaking Existing Functionality
|
||||
|
||||
**Mitigation:**
|
||||
- All changes must pass existing tests
|
||||
- Incremental approach (one file/feature at a time)
|
||||
- CI gates prevent regressions
|
||||
|
||||
### Risk: Violating Invariants
|
||||
|
||||
**Mitigation:**
|
||||
- P2.7 documents invariants first
|
||||
- CI enforces invariants automatically
|
||||
- Design review before implementation
|
||||
|
||||
### Risk: Scope Creep
|
||||
|
||||
**Mitigation:**
|
||||
- Clear "what P2 excludes" section
|
||||
- Acceptance criteria defined upfront
|
||||
- Can pause/resume at item boundaries
|
||||
|
||||
### Risk: Documentation Drift
|
||||
|
||||
**Mitigation:**
|
||||
- P2.7 creates invariant documentation
|
||||
- Progress docs updated per item
|
||||
- Index updated per P1.5 rules
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Quantitative
|
||||
|
||||
- **P2.6:** `any` usage count reduced (target: 50%+ reduction in `src/core/` and public interfaces)
|
||||
- **P2.7:** All invariants documented (target: 100% coverage)
|
||||
- **P2.x:** Combined edge case tests added (target: 3+ scenarios)
|
||||
|
||||
### Qualitative
|
||||
|
||||
- **Type safety:** Code is more maintainable, fewer runtime type errors possible
|
||||
- **Documentation:** New contributors understand invariants quickly
|
||||
- **Resilience:** Edge cases are better understood and tested
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External Dependencies
|
||||
|
||||
- None — P2 is self-contained polish work
|
||||
|
||||
### Internal Dependencies
|
||||
|
||||
- **P2.7 → P2.6/P2.x:** Invariant documentation helps validate other work
|
||||
- **P2.6 → P2.x:** Type improvements may help P2.x implementation
|
||||
|
||||
### Blocking Dependencies
|
||||
|
||||
- None — P2 can start immediately after P1.5
|
||||
|
||||
---
|
||||
|
||||
## Timeline Estimate
|
||||
|
||||
**P2.7:** 2-4 hours (documentation only)
|
||||
**P2.6:** 8-16 hours (incremental type cleanup)
|
||||
**P2.x:** 16-32 hours (varies by item complexity)
|
||||
|
||||
**Total:** 26-52 hours (can be spread over multiple sessions)
|
||||
|
||||
**Note:** These are estimates. Actual time depends on codebase complexity and test coverage.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (After Design Approval)
|
||||
|
||||
1. **Review this design** — Ensure scope and constraints are correct
|
||||
2. **Approve invariants list** — Confirm nothing is missing
|
||||
3. **Prioritize P2 items** — Decide execution order
|
||||
4. **Begin P2.7** — Document invariants first (recommended)
|
||||
5. **Execute incrementally** — One item at a time, pause/resume as needed
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-12-22
|
||||
**Status:** Design-Only (No Implementation)
|
||||
**Next Action:** Review and approve design before proceeding
|
||||
|
||||
Reference in New Issue
Block a user