docs: add specification for handling indices

[wjones127]

This document doesn't change the spec but instead writes down what the existing code does. So I'm not sure it needs a vote. However, I would like to get lots of eyes on it and have multiple approvals if possible.

[Xuanwo]

Love this

[github-actions]

Documentation Review

This is a well-written specification document that clearly explains the existing index handling behavior. The diagrams add valuable visual context.

No critical issues found. The documentation is clear, accurate, and well-organized.

Minor observations (non-blocking):

1. Typo on line ~129: "singificant" should be "significant" in the compaction section.

2. Line ~95: The phrase "The allows reuse" appears to be missing a word - should likely be "This allows reuse".

Overall, this is an excellent addition to the format specification.

[github-actions]

PR Review: docs: add specification for handling indices

This is a well-written documentation PR that formalizes the existing index behavior. The explanations are clear and the diagrams add significant value.

Minor Issues

P1: Typos in the documentation

There are a couple of typos that should be fixed before merging:

1. In "Index Storage" section: "The allows reuse" should be "This allows reuse"
2. In "Compaction and remapping" section: "singificant write ampliciation" should be "significant write amplification"

Observations

The documentation covers the key concepts well:

• Index segment model with fragment bitmaps
• Handling of deleted/invalidated rows
• Three compaction strategies with clear trade-offs
• Stable row ID feature marked as experimental

The design principles (on-demand loading, progressive loading, immutability) are clearly articulated and match the existing implementation behavior.

---

Reviewed with Claude Code