Complete bd-175, bd-176, bd-177: Memory tests, corruption docs, prefix validation

- bd-175: Added comprehensive test coverage for internal/storage/memory backend
  - All CRUD operations, dependencies, labels, comments
  - Thread safety with race detection
  - LoadFromIssues and counter sync
  - Fixed batch duplicate detection

- bd-176: Documented corruption vs collision distinction
  - Added FAQ entry explaining logical vs physical corruption
  - Updated TROUBLESHOOTING with clear guidance
  - Clarified when to use collision resolution vs reimport

- bd-177: Added prefix validation in SQLite mode
  - Validates explicit IDs match configured prefix
  - Works in both CreateIssue and CreateIssues
  - Comprehensive tests for single and batch operations
This commit is contained in:
Steve Yegge
2025-10-27 11:29:08 -07:00
parent f5e1a9811a
commit 68ffb9ed40
6 changed files with 1171 additions and 27 deletions

31
FAQ.md
View File

@@ -361,6 +361,37 @@ bd create "Fix bug" -p 1
See [ADVANCED.md#git-worktrees](ADVANCED.md#git-worktrees) for details.
### What's the difference between SQLite corruption and ID collisions?
bd handles two distinct types of integrity issues:
**1. Logical Consistency (Collision Resolution)**
The hash/fingerprint/collision architecture prevents:
- **ID collisions**: Same ID assigned to different issues (e.g., from parallel workers or branch merges)
- **Wrong prefix bugs**: Issues created with incorrect prefix due to config mismatch
- **Merge conflicts**: Branch divergence creating conflicting JSONL content
**Solution**: `bd import --resolve-collisions` automatically remaps colliding IDs and updates all references.
**2. Physical SQLite Corruption**
SQLite database file corruption can occur from:
- **Disk/hardware failures**: Power loss, disk errors, filesystem corruption
- **Concurrent writes**: Multiple processes writing to the same database file simultaneously
- **Container scenarios**: Shared database volumes with multiple containers
**Solution**: Reimport from JSONL (which survives in git history):
```bash
mv .beads/*.db .beads/*.db.backup
bd init
bd import -i .beads/issues.jsonl
```
**Key Difference**: Collision resolution fixes logical issues in the data. Physical corruption requires restoring from the JSONL source of truth.
**When to use in-memory mode (`--no-db`)**: For multi-process/container scenarios where SQLite's file locking isn't sufficient. The in-memory backend loads from JSONL at startup and writes back after each command, avoiding shared database state entirely.
## Getting Help
### Where can I get more help?