docs: metadata schema evolution protocol

.learnings/2026-02-21-metadata-schema-evolution-protocol.md

@@ -0,0 +1,33 @@
+# Metadata Schema Evolution Protocol
+
+**Date:** 2026-02-21
+
+## Original Prompt
+
+> Create a formal metadata schema evolution protocol for all metadata objects created by the system. Ensure that this documentation is referenced in claude memory for future tickets that make changes to the metadata.
+
+## What I Learned
+
+- CipherBox has 10 metadata objects across TypeScript and Rust that must produce byte-identical JSON
+- Fields were added informally (optional + serde defaults) without version bumps through Phase 13 -- no protocol existed
+- The `FileMetadata.version` field stayed at `'v1'` despite two additive changes (`encryptionMode`, `versions`) -- this is defensible but means the version field is useless for feature detection
+- `FolderMetadata` had a clean-break v1->v2 migration (pre-production vault wipe) -- this strategy is only valid when all data can be wiped
+- Changing a default value is a breaking change in disguise (e.g., changing `encryptionMode` default from `'GCM'` to `'CTR'` would silently decrypt old files with the wrong algorithm)
+- Objects without their own version field (FolderEntry, FilePointer, VersionEntry, DeviceEntry) evolve through their parent's version
+- The recovery tool (`apps/web/public/recovery.html`) has its own inline crypto implementations and must be updated independently for any change affecting file discovery or decryption
+
+## What Would Have Helped
+
+- A formal protocol from Phase 12.6 onward (when per-file IPNS was introduced) would have prevented the informal pattern
+- Cross-platform round-trip tests (TS -> Rust -> TS) should be standard for every schema change
+
+## Key Files
+
+- `docs/METADATA_SCHEMAS.md` -- complete reference for all 10 metadata objects
+- `docs/METADATA_EVOLUTION_PROTOCOL.md` -- formal evolution rules and checklist (Section 4 is the actionable checklist)
+- `packages/crypto/src/file/types.ts` -- FileMetadata, VersionEntry, FilePointer types
+- `packages/crypto/src/folder/types.ts` -- FolderMetadata, FolderEntry, FolderChild types
+- `packages/crypto/src/registry/types.ts` -- DeviceRegistry, DeviceEntry types
+- `packages/crypto/src/vault/types.ts` -- EncryptedVaultKeys, VaultInit types
+- `apps/desktop/src-tauri/src/crypto/folder.rs` -- Rust equivalents for all FUSE-relevant types
+- `apps/web/public/recovery.html` -- standalone recovery tool with inline metadata parsing

.planning/STATE.md

@@ -12,7 +12,7 @@ See: .planning/PROJECT.md (updated 2026-02-11)
 Phase: 13 (File Versioning)
 Plan: 5 of 5
 Status: Phase complete
-Last activity: 2026-02-19 -- Completed 13-05-PLAN.md (Recovery Tool + Final Verification)
+Last activity: 2026-02-21 -- Completed quick task 019 (Metadata Schema Evolution Protocol)
 
 Progress: [#########################] (M1 complete, M2 Phase 12 complete, Phase 12.2 complete, Phase 12.3 complete, Phase 12.3.1 complete, Phase 12.4 complete, Phase 12.5 complete, Phase 12.6 complete, Phase 12.1 complete, Phase 11.1: 7/7 COMPLETE, Phase 11.2: 3/3 COMPLETE, Phase 13: 5/5 COMPLETE)
 
@@ -203,6 +203,7 @@ Recent decisions affecting current work:
 | 016 | Refine wallet and MFA UI elements         | 2026-02-16 | d004eb0 | [016-refine-wallet-and-mfa-ui-elements](./quick/016-refine-wallet-and-mfa-ui-elements/)                     |
 | 017 | Desktop binary staging release            | 2026-02-19 | 8351fd2 | [017-desktop-binary-staging-release](./quick/017-desktop-binary-staging-release/)                           |
 | 018 | E2E versioning tests                      | 2026-02-19 | 3fd131e | [018-e2e-versioning-tests](./quick/018-e2e-versioning-tests/)                                               |
+| 019 | Metadata schema evolution protocol        | 2026-02-21 | dcb49e1 | [019-metadata-schema-evolution-protocol](./quick/019-metadata-schema-evolution-protocol/)                   |
 
 ### Research Flags
 
@@ -222,12 +223,12 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-02-19
-Stopped at: Completed quick task 018: E2E versioning tests
+Last session: 2026-02-21
+Stopped at: Completed quick task 019: Metadata Schema Evolution Protocol
 Resume file: None
 Next: Run /gsd:discuss-phase 14 or /gsd:plan-phase 14 for User-to-User Sharing.
 
 ---
 
 _State initialized: 2026-01-20_
-_Last updated: 2026-02-19 after completing quick task 018 (E2E versioning tests)_
+_Last updated: 2026-02-21 after completing quick task 019 (Metadata Schema Evolution Protocol)_