beads/docs/ADAPTIVE_IDS.md
Giulio Mecocci 87f32865cf
feat: support issue_id_mode=counter for sequential IDs (#2013)
* 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.
2026-02-22 23:49:46 -08:00

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 database
  • N = 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:

  1. Base length (e.g., 4 chars)
  2. Base + 1 (e.g., 5 chars)
  3. 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:

  1. Continue using 6-char IDs by default
  2. Can opt into adaptive mode by setting config (new IDs will use adaptive length)
  3. 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

  1. Default is good: The 25% threshold works well for most use cases
  2. Active archival: Delete closed issues to keep database small and IDs short
  3. Consistency: Set min_hash_length if you want all IDs to be same length
  4. 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.