docs: V1 upgradeability discovery & implementation strategy

[bitsofsteve]

What this is

A discovery + alignment document for the V1 upgradeability work (no production code changes — docs only). The goal is to give the team a shared, evidence-backed picture before we commit to an implementation.

📄 docs/upgrades/V1_UPGRADE_DISCOVERY_AND_STRATEGY.md
🔬 docs/upgrades/phase0_repro.py — runnable: uv run python docs/upgrades/phase0_repro.py

The headline finding

The one historical backward-compat break — Drive folder names started embedding the version at 0.1.112 — is already hot-patched by #280 (_filter_patch_compatible). A solo patch upgrade with one existing folder resolves correctly today.

So the real finding isn't "something is broken" — it's "there is no upgrade system, only point-fixes." The Phase-0 repro drives the real gdrive_transport functions and shows the residual sharp edges:

• Scenario A — solo patch upgrade, one folder
• Scenario B — two patch folders coexist → RuntimeError, user must hand-delete a folder on Drive ❌ (violates the "user shouldn't have to care" invariant)
• Scenario C — minor bump → silent strand (correct behaviour, but it's the unmarked V1/V2 boundary)

What the doc covers

• The contract — patch skew = translation (higher version is the service-bus manager); minor/major = forced upgrade (no translation)
• Findings — audit matrix of every serialized surface; all content formats clean within 0.1.93 → 0.1.117
• "Biting" issues — unenforced MIN_SUPPORTED, un-versioned local caches, no integrity re-verify on restore, independently-versioned sub-packages
• Pre-work — six independently-valuable fixes that strengthen any design (version-stamping, seam centralization, frozen corpus, merge-tolerant folder resolution, …)
• Technical design — translator (upcast/downcast registry) + upgrader (cataloguing + integrity) anchored on the real seams
• Phasing, test strategy, and forward-compat with V2

Decisions we need to align on (see §8)

1. Folder naming: keep version-scoped folders and bridge them, or retire version-in-folder-name and version the content instead (doc recommends the latter)
2. Enforce a real MIN_SUPPORTED floor in V1?
3. Audit sub-package serialized formats in V1, or track separately?

Opening this for team review — the structure and the §8 decisions are the things to react to first.