docs: Add Mutation-Invariant Mismatch bug pattern (#13)#27
Merged
Conversation
Document the step array resizing bug where handleSetTrackStepCount violates the invariant that arrays must be exactly MAX_STEPS (128). - Add comprehensive spec in specs/research/STEP-ARRAY-INVARIANT-BUG.md - Add Bug Pattern #13: Mutation-Invariant Mismatch (Dual Truth Source) - Include codebase audit results identifying all affected handlers - Document that mock-durable-object.ts replicates the same bugs - Provide detection scripts and prevention checklist Key findings: - handleSetTrackStepCount truncates arrays, violating invariants - handleToggleStep expands arrays via push() - Neither calls validateAndRepairState after mutation - 6 handlers don't call validation (only 2 have array risk)
- Add "How We Know We're Right" section with evidence table - Prove all Model B (variable arrays) evidence was introduced in af466ff - Document scheduler proof: guard implies arrays can be longer than stepCount - Add complete implementation requirements with file list - Document conflicting documentation in bug-patterns.ts that must be fixed - Add client-side fix requirements for grid.tsx
- Document positive consequences (invariants pass, no data loss, hash stability) - Confirm UI already handles 128-length arrays correctly (slices for display) - Explain backward compatibility (repair auto-pads on load) - Analyze state payload size impact (~1KB per track, mitigated by gzip) - Add rollout considerations (must deploy client+server atomically) - List specific tests that verify wrong behavior and must be updated
- Document snapshot storm mechanics and how it would manifest - List existing defenses (debounce, threshold, interval) - Add detection methods (metrics to monitor, log patterns) - Describe resolution strategy if storm detected during rollout - Add "The Vanishing Pattern" demo scenario showing data loss vs preservation - Include test script for the demo - Add user story for acceptance criteria
- Show original SET_TRACK_STEP_COUNT that we're restoring (just sets stepCount) - Document the root cause: design intent was never explicitly stated - Identify documentation gap: invariant enforced design but didn't explain WHY - Add lesson learned: invariants should include rationale, not just checks - Note that LESSONS-LEARNED.md used <= 128 not === 128, adding to confusion
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Document the step array resizing bug where handleSetTrackStepCount
violates the invariant that arrays must be exactly MAX_STEPS (128).
Key findings: