* feat: support issue_id_mode=counter for sequential IDs (GH#2002) When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`, `bd create` now assigns monotonically increasing integer IDs instead of hash-based IDs. The counter is stored in a new `issue_counter` table (one row per prefix) and incremented atomically within the same transaction as the issue insert. - Add `issue_counter` table to schema (version bumped to 5) - Add migration 006 to create `issue_counter` table on existing databases - Add `GetNextIssueCounter()` to queries.go (standalone transaction, for callers outside CreateIssue) - Modify `generateIssueID()` to check `issue_id_mode` config and use counter path when set to "counter"; hash mode remains the default when unset - Explicit `--id` flag continues to take precedence over counter mode - Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes, TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter, TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable * docs: document issue_id_mode=counter feature (GH#2002) Add documentation for the sequential counter ID mode across all relevant docs: - docs/CONFIG.md: new issue_id_mode namespace entry and full example section with tradeoff table, migration guidance, and per-prefix counter isolation - .beads/BD_GUIDE.md: counter mode section with when-to-use, migration considerations, and explicit --id override behavior - docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference to CONFIG.md - website/docs/reference/configuration.md: issue_id_mode under ID Generation with comparison table * fix: seed counter from existing issues when enabling counter mode (GH#2002) When issue_id_mode=counter is enabled on a repo that already has manually-created sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1, causing immediate collisions. Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the highest numeric suffix for the given prefix, and seeds the issue_counter table from there. The function is idempotent (skips if a counter row already exists) and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2). The seeding is called at first counter use: in generateIssueID() (issues.go) and GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix. Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress). * feat: add bd config schema and describe commands for agent discoverability (GH#2002) Adds machine-readable config schema so agents can programmatically discover all available configuration keys without reading source code. - internal/config/schema.go: new ConfigKeyDef struct and Schema slice with 43 entries covering core, sync, routing, jira, linear, gitlab, team, mail, and YAML-only keys; includes type, default, valid values, description, and storage location per key - cmd/bd/config.go: adds 'bd config schema' (table + --json) and 'bd config describe <key>' (single-key detail + --json) subcommands Usage: bd config schema bd config schema --json | jq '.[] | select(.key == "issue_id_mode")' bd config describe issue_id_mode bd config describe jira.url --json * refactor: remove overengineered config schema (keep docs only) Remove the configSchemaCmd and configDescribeCmd subcommands added in the previous commit, along with internal/config/schema.go (390 lines of config key definitions). These are out of scope for GH#2002.
5.9 KiB
Adaptive ID Length
Feature: bd-ea2a13
Status: Implemented (v0.21+)
Overview
Beads uses adaptive hash ID lengths that automatically scale based on database size, optimizing for readability in small databases while preventing collisions as databases grow.
Motivation
- Small databases (0-500 issues): Very short, readable IDs like
bd-a3f2(4 chars) - Medium databases (500-1500 issues): Slightly longer IDs like
bd-7f3a8(5 chars) - Large databases (1500+ issues): Standard IDs like
bd-7f3a86(6 chars)
Users who actively archive old issues can keep their IDs shorter over time.
How It Works
Birthday Paradox Math
The collision probability is calculated using:
P(collision) ≈ 1 - e^(-n²/2N)
Where:
n= number of issues in databaseN= total possible IDs (36^length for lowercase alphanumeric)
Default Thresholds (25% max collision)
| Database Size | ID Length | Collision Probability |
|---|---|---|
| 0-500 | 4 chars | ~7% at 500 |
| 501-1500 | 5 chars | ~2% at 1500 |
| 1501+ | 6 chars | continues scaling |
Collision Resolution
If a collision occurs (rare), the algorithm automatically tries:
- Base length (e.g., 4 chars)
- Base + 1 (e.g., 5 chars)
- Base + 2 (e.g., 6 chars)
With 10 nonces per length, giving 30 attempts total.
Configuration
Adaptive ID length is automatically enabled when using id_mode=hash. You can customize the behavior:
Max Collision Probability
Default: 25% (0.25)
# More lenient (allow up to 50% collision probability)
bd config set max_collision_prob "0.50"
# Stricter (only allow 1% collision probability)
bd config set max_collision_prob "0.01"
Minimum Hash Length
Default: 4 chars
# Start with 5-char IDs minimum
bd config set min_hash_length "5"
# Very short IDs (use with caution)
bd config set min_hash_length "3"
Maximum Hash Length
Default: 8 chars
# Allow even longer IDs for huge databases
bd config set max_hash_length "10"
Examples
Default Configuration
# Initialize with hash IDs
bd init --id-mode hash --prefix myproject
# First 500 issues get 4-char IDs
bd create "Fix bug" -p 1
# → myproject-a3f2
# After 1000 issues, switches to 5-char IDs
bd create "Add feature" -p 1
# → myproject-7f3a8c
# At 10,000 issues, uses 6-char IDs
bd create "Refactor" -p 1
# → myproject-b9d1e4
Custom Configuration
# Very strict collision tolerance
bd config set max_collision_prob "0.01"
# With 1% threshold and 100 issues, uses 4-char IDs
# (collision probability is ~0.3% with 4 chars)
# Force minimum 5-char IDs for consistency
bd config set min_hash_length "5"
# All IDs will be at least 5 chars now
bd create "Task" -p 1
# → myproject-7f3a8
Collision Probability Table
Use scripts/collision-calculator.go to explore collision probabilities:
go run scripts/collision-calculator.go
Output shows:
- Collision probabilities for different database sizes and ID lengths
- Recommended ID lengths for different thresholds
- Expected number of collisions
- Adaptive scaling strategy
Implementation Details
Location
- Algorithm:
internal/storage/dolt/adaptive_length.go - ID generation:
internal/storage/dolt/dolt.go(generateHashID) - Tests:
internal/storage/dolt/adaptive_length_test.go - E2E tests:
internal/storage/dolt/adaptive_e2e_test.go
Database Schema
Configuration is stored in the config table:
INSERT INTO config (key, value) VALUES ('max_collision_prob', '0.25');
INSERT INTO config (key, value) VALUES ('min_hash_length', '4');
INSERT INTO config (key, value) VALUES ('max_hash_length', '8');
Performance
- Collision probability calculation: ~10ns per call
- ID generation with adaptive length: ~300ns (same as before)
- Database query to count issues: ~100μs
Migration
Existing Databases
Existing databases with 6-char IDs will:
- Continue using 6-char IDs by default
- Can opt into adaptive mode by setting config (new IDs will use adaptive length)
- Old IDs remain unchanged
Sequential to Hash Migration
When migrating from sequential IDs to hash IDs with bd migrate --to-hash-ids:
- Uses adaptive length algorithm for new IDs
- Preserves existing sequential IDs
- References are automatically updated
Best Practices
- Default is good: The 25% threshold works well for most use cases
- Active archival: Delete closed issues to keep database small and IDs short
- Consistency: Set
min_hash_lengthif you want all IDs to be same length - Monitoring: Run collision calculator periodically to check health
Future Enhancements
Potential improvements (not yet implemented):
- Automatic scaling notifications: Warn when approaching threshold
- Per-workspace thresholds: Different configs for different projects
- Dynamic adjustment: Auto-adjust threshold based on observed collision rate
- Compaction-aware: Don't count compacted issues in collision calculation
Alternative: Sequential Counter IDs
Adaptive hash IDs are the default, but beads also supports sequential integer IDs
(bd-1, bd-2, ...) for projects that prefer human-readable numbering.
Counter mode is controlled by the issue_id_mode config key:
# Switch to sequential IDs
bd config set issue_id_mode counter
# Revert to hash IDs (default)
bd config set issue_id_mode hash
Tradeoff:
- Hash IDs (this document): Collision-free across parallel branches and agents; IDs are less predictable but always unique.
- Counter IDs: Human-friendly and sequential; require care in multi-branch workflows where counters can diverge.
See CONFIG.md for full documentation on issue_id_mode=counter, including migration
guidance and per-prefix counter isolation.
Related
- Migration Guide - Converting from sequential to hash IDs
- Configuration - All configuration options