index-keyspace-evolutionlisted
Install: claude install-skill Goldziher/basemind
# Index Keyspace Evolution
Use this when adding a new Fjall keyspace, extending an existing key encoding, or changing the value shape of an indexed record.
## Decide if you need a schema bump
Bumping `INDEX_SCHEMA_VER` triggers auto-wipe of `.basemind/views/<view>/index.fjall/` on the user's next scan. The next scan rebuilds from the msgpack blobs — no data loss, but a one-time scan cost. Bump when:
- The byte layout of an existing key changes.
- A `SymbolKind` ordinal would shift (you reordered the enum — don't).
- A value's msgpack shape lost a field or renamed one.
Do **not** bump when:
- Adding a brand-new partition (no existing entries to migrate).
- Adding a `#[serde(default)]`-defaulted field to an indexed value.
- Adding a new `SymbolKind` variant at the tail (the `u8` mapping is stable).
## Steps
1. **Encoder + decoder + tests in `src/index/keys.rs`**
- Add `<partition>_key(...) -> Vec<u8>` and `<partition>_prefix(...) -> Vec<u8>`.
- Add `parse_<partition>_key(&[u8]) -> Result<(...), …>`.
- Add unit tests for round-trip + prefix isolation: insert two keys with a shared prefix that differ only in the suffix, scan the prefix, confirm the wrong sibling is excluded.
2. **Open the partition in `src/index/mod.rs`**
- Add the field to `IndexDb`.
- Open via `db.keyspace("<name>", PartitionCreateOptions::default())` next to the others.
- If used only for reads, mark `#[allow(dead_code)]` until a writer / reader exists.
3. **Writer in `src/index/wri