Block It Out

Instance Sync Handoff

Goal

Finish the recurring-sync simplification so the engine is predictable:

• recurring source events are flattened into concrete source instances
• destination shadows are always one-off events
• identity is SourceInstanceKey = normalized series/event ID + anchored instance date
• moved exceptions keep stable identity while their blocked slot can move

Current Canonical Model

Production

• ShadowNoteManager.SourceInstanceKey is the canonical recurring-instance identity.
• New shadow notes include InstanceDate and still parse legacy note formats.
• Sync now plans concrete source instances, matches exact instance IDs first, and falls back to legacy source IDs only for migration/compatibility.
• New destination shadows do not copy recurrence rules.
• Snapshot-store records now use the instance-aware source key.

Formal Model

• TLAPlus/ShadowSyncInstances.tla is the authoritative model.
• TLAPlus/ShadowSyncInstances_Small.cfg is the current TLC config.
• TLAPlus/ShadowSyncEdgeCases.tla is historical and documents the older series-level abstraction.

Completed

• Refactor sync matching toward per-instance identity.
• Stop creating recurring destination shadows.
• Add InstanceDate to new shadow notes with legacy parsing fallback.
• Add tests for moved recurring occurrence update behavior.
• Add tests for two moved exceptions in one series staying distinct.
• Add TLA+ instance-based model and verify it with TLC.
• Fix delete/suppress UI flow to pass the exact stored source key instead of only the normalized source ID.
• Add snapshot-store v3 migration from legacy rawEventID@timestamp keys to instance-aware keys.
• Add sync-time shadow-store rekey path using shadowEventID as a recovery path for touched legacy records.
• Add migration tests for legacy key rewrite and merge-on-collision behavior.
• Update SyncInvariants to use instance-aware store keys instead of the obsolete sourceEventID@timestamp assumption.
• Add suppression/unsuppression integration coverage for instance-aware recurring shadows.
• Add sync-time rekey coverage proving an existing shadow can move a legacy store record onto the exact instance key by shadowEventID.
• Clean up remaining stale key-shape assumptions in cleanup paths (suppressedShadows, removed-destination cleanup).

Remaining Work

• Audit all remaining legacy-ID assumptions outside the main sync path.
• Add store tests covering sync-time rekey by shadowEventID, not just load-time migration.
• Decide whether to keep or prune unreachable legacy fallback paths after one release cycle.
• Run a fuller test command once the shared scheme/test-plan situation is sorted out.

Compatibility Notes

• Existing shadow event notes are intentionally backward-compatible.
• Existing snapshot-store records are migrated on load to v3.
• If load-time migration cannot perfectly infer the intended key from older data, the sync-time rekey path should move touched records onto the correct key when the existing shadow is encountered again.

Verification Status

• App scheme build: passing
• Block It OutTests target build: use the shared Debug scheme; a raw target build without a scheme still defaults to Release and breaks @testable import Block_It_Out
• TLC for ShadowSyncInstances.tla: passing
• Working CLI shape for targeted tests: xcodebuild test -project "Block It Out.xcodeproj" -scheme "Block It Out - Sim (StoreKit)" -destination 'platform=iOS Simulator,OS=18.6,name=iPhone 16' -only-testing:'Block It OutTests/ShadowSnapshotStoreTests' -only-testing:'Block It OutTests/SyncPropertyTests'
• Prior CLI failure cause: -only-testing must use the bundle name Block It OutTests (with spaces), not BlockItOutTests

Next Slice In Progress

• Decide whether to keep or prune unreachable legacy fallback paths after one release cycle.

Current Work Plan

• [~] Simplify SyncService’s occurrence-move logic so recurring shadows no longer suppress per-instance updates, normalize identity handling, and eliminate overlapping branches that rely on normalized series IDs.
• Verify the in-app calendar delete/suppress/recreate flow honors the new per-instance shadow identity and still routes suppression requests through ShadowSnapshotStore.
• Confirm we have not altered the shadow note/event encoding semantics in a way that regresses existing entries (no audit logs needed because all formats already normalize/parse as stored).
• Run TLC against ShadowSyncInstances.tla with /opt/homebrew/bin/java to ensure the formal model still reflects our intention.