Investigation: can the legacy v1/v2 storage-wrapping code be removed based on telemetry?

[tnaum-ms]

Background

PR #726 added a per-version census of stored connection items to the connectionStorage.stats activation telemetry event so we can answer one concrete question: how many real installs still carry pre-v3 storage records, and is it safe to delete the legacy read-time wrapping code?

The wrapping code in question lives in src/services/connectionStorageService.ts:

• fromStorageItem — switch on item.version with cases for '3.0', '2.0', and default (v1, no version field).
• wrapV1AsV2 — in-memory upgrade of v1 records to the v2 shape.
• wrapV2AsCurrent — in-memory upgrade of v2 records to the current shape.
• convertV2ToConnectionItem — used only on the v2 branch.

Today this runs on every read of every connection item. It is correct but it is dead weight once the installed base no longer holds any v1/v2 records.

What telemetry to look at

Event: connectionStorage.stats (fires once per activation, after cleanup).

Aggregate counters (across both Clusters and Emulators zones):

• v1Items, v2Items, v3Items, unknownVersionItems
• hasLegacyItems — boolean property, 'true' iff v1Items + v2Items > 0.

Per-zone counters:

• clusters_v1Items, clusters_v2Items, clusters_v3Items, clusters_unknownVersionItems
• emulators_v1Items, emulators_v2Items, emulators_v3Items, emulators_unknownVersionItems

Supporting signal on resolvePostMigrationErrors:

• previousCleanupVersion — shows installs crossing the legacy '0.8.1' marker → integer counter boundary (added in the same PR).

Questions to answer

1. What fraction of unique installs report hasLegacyItems = 'true' over the most recent full release window?
2. What is the absolute count of v1 vs v2 items? (v2 is younger than v1, so removal of v1 may unblock first.)
3. Is the legacy population shrinking release-over-release? Plot the trend.
4. Are there outlier installs holding a large number of legacy items? (a few power users may matter more than the percentage suggests).
5. Any unknownVersionItems > 0 reports? Those would indicate either future-format records or corruption and are worth flagging separately.

Decision criteria

• Remove v1 wrapping (wrapV1AsV2, default branch in fromStorageItem) when:
  • v1Items = 0 across two consecutive release windows, AND
  • no install reports v1Items > 0 in the most recent 30 days.
• Remove v2 wrapping (wrapV2AsCurrent, convertV2ToConnectionItem, '2.0' branch) when the same criteria hold for v2Items.
• Defer removal as long as hasLegacyItems = 'true' for any non-trivial cohort; document the next check-in date.

Tasks

• Pull connectionStorage.stats data from telemetry for the current and previous release windows.
• Quantify v1Items / v2Items populations (unique installs, absolute counts, distributions).
• Decide per-format whether removal is safe now, in a later milestone, or still gated.
• If removal is approved, file a follow-up PR deleting wrapV1AsV2 / wrapV2AsCurrent and the corresponding branches in fromStorageItem. Also drop matching tests.
• If removal is deferred, file a follow-up reminder issue for the next milestone with the deferral rationale.

Out of scope

• Forced on-disk migration of legacy records — explicitly avoided in PR perf(storage): speed up connection load and clarify in-memory wrapping #726 (read-time wrapping is intentional). Only the read-side wrapping code is on the chopping block.
• The STORAGE_CLEANUP_VERSION integer counter is a separate marker and unrelated to whether wrapping can be removed.

References

• PR perf(storage): speed up connection load and clarify in-memory wrapping #726 — feat: per-version item census in stats telemetry (e7f2169)
• PR perf(storage): speed up connection load and clarify in-memory wrapping #726 — fix: replace cleanup-schema marker with integer counter (12f5163)
• Local design notes: docs/ai-and-plans/PRs/726-storage-load-optimization/