feat(filestore): Migrate version storage layout to per-document subdirectories

[ontehfritz]

this will be able to now handles 10s of thousands of versions

Summary by CodeRabbit

• Infrastructure Updates

  • Reorganized on-disk version storage to a per-document directory layout.
  • Automatic migration from legacy flat format with backward compatibility and transparent reads/writes.
  • Version discovery and retrieval now support both legacy and per-document layouts.

• Tests

  • Updated tests to assert per-document layout behavior.
  • Added migration and subdirectory-specific tests to validate migration, integrity, and symlink updates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b906d07c-be73-4063-a652-8bb1fafb750b

📥 Commits

Reviewing files that changed from the base of the PR and between 0368a70 and d43e534.

📒 Files selected for processing (1)

• server/internal/store/store_test.go

---

Walkthrough

Version storage layout changed from flat files (versions/{base}.v{N}) to per-document subdirectories (versions/{base}/v{N}) with dual-layout support and on-write migration. Path-resolution, version writes, and archive checks were refactored; tests updated and new migration tests added.

Changes

Cohort / File(s)	Summary
Store implementation server/internal/store/store.go	Refactored version discovery, retrieval, and writes to prefer per-doc subdirectories (versions/{base}/v{N}) while falling back to legacy flat files. Added helpers: prepareExistingDoc, newVersionFilePath, newVersionSymlinkTarget, resolveVersionFile, migrateFlatFile, migrateToPerDocDir. Archive check signature changed to (bool, error).
Store tests and migration coverage server/internal/store/store_test.go	Updated assertions to per-doc directory layout; added tests for per-doc writes, nested-path behavior, and TestWrite_MigratesOldLayoutToPerDoc which constructs legacy flat layout, triggers migration on Write, verifies removal of flat files, creation of per-doc dirs/files, symlink repointing, and successful chain verification.
Handler test alignment server/internal/handler/handler_test.go	Adjusted tampering path in TestVersionsChainValid from dir/versions/doc.md.v1 to dir/versions/doc.md/v1 to reflect per-document subdirectory layout.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Store
    participant FS as FileSystem
    participant Verifier

    Client->>Store: Write(document)
    Store->>FS: resolveVersionFile(doc)
    alt per-doc layout exists
        FS-->>Store: path to versions/doc/vN
    else legacy flat layout
        FS-->>Store: no per-doc dir
        Store->>FS: migrateToPerDocDir(doc) / move flat files -> versions/doc/vN
        FS-->>Store: migration result
    end
    Store->>FS: create new versions/doc/vN (write file)
    Store->>FS: update current symlink -> versions/doc/vN
    Store->>Verifier: VerifyChain(doc)
    Verifier-->>Store: verification result
    Store-->>Client: Write response

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~40 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	Title check skipped as CodeRabbit has written the PR title.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-scalable-filestore

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}