beads_rust

The beads_rust E2E test harness produces machine-parseable JSONL logs and structured JSON files to document test execution. These artifacts are used for analyzing command execution, file system states, and test performance.

All artifacts are stored in the following directory structure: target/test-artifacts/<suite>/<test>/

The project is organized into several functional modules:

• src/model/: Core data structures (Issue, Dependency, Event, Hash).
• src/storage/: Data persistence layer (SQLite schema, migrations, CRUD operations for issues, dependencies, labels, and events).
• src/export/: Logic for JSONL export/import and local history management (.br_history/).
• src/cli/: CLI command definitions and argument parsing.
• src/git/: Minimal git integration for repository and branch detection.
• tests/: Integration, conformance (vs legacy bd), and end-to-end CLI tests.

beads_rust/
├── src/
│   ├── model/      # Issue, Dependency, Event, Hash
│   ├── storage/    # SQLite, Schema, Migrations, CRUD
│   ├── export/     # JSONL, History
│   ├── cli/        # Command definitions
│   └── git/        # Git detection
└── tests/          # Integration, Conformance, E2E

The br (Beads Rust) tool targets the classic issue tracker (SQLite + JSONL) and intentionally omits Gastown/daemon/hook automation.

Included in br v1:

• Core CRUD: init, create, update, close, reopen, delete (tombstone).
• Views & Queries: list, show, ready, blocked, search, stats, count, stale, orphans.
• Structure: dep, label, comments.
• Sync: sync --flush-only, sync --import-only (no git operations).
• Config: config get/set/list/unset (yaml-only).

Explicitly excluded in br v1:

• Gastown features (gate, agent, molecule, rig, convoy, hop, session).
• Daemon, RPC, auto-git hooks, auto-commit, or auto-push.
• Linear/Jira integrations.
• TUI or visualization features (these are delegated to bv).

The br (Beads Rust) project is a port of the legacy Go-based beads codebase. It is designed as a lightweight, non-invasive tool for managing issues and tasks using a hybrid SQLite and JSONL storage system.

Unlike the legacy version, br follows a strict design philosophy to ensure simplicity and user control:

• No automatic git hooks: Users must manually add hooks if they want automation.
• No automatic git operations: The tool will not perform auto-commits or auto-pushes.
• No daemon/RPC: It is a simple CLI-only tool without background processes.
• Explicit over implicit: Every git operation requires an explicit command from the user.

Issues are marked "dirty" whenever they are modified (e.g., CreateIssue, UpdateIssue, AddLabel, AddComment). This allows for efficient incremental exports.

Key Operations:

• MarkIssueDirty(issueID): Marks a single issue with a timestamp.
• GetDirtyIssues(): Returns issue IDs in FIFO order (by marked_at).
• ClearDirtyIssuesByID(issueIDs): Clears dirty flags for specific IDs (use this only after a successful export).

Incremental Export Workflow:

1. Query dirty_issues (FIFO).
2. For each ID, compare its current content_hash against the stored export_hash.
3. If hashes differ, include in export and write to JSONL.
4. Update the issue's export_hash with the new hash.
5. Call ClearDirtyIssuesByID() for the exported IDs.

When running br in JSON mode, failures emit a structured JSON error object on stdout.

• Detection: Use the process exit code to distinguish between successful data and error envelopes.
• Schema: The structure of the error object can be inspected using br schema error --format json.
• Partial Batches: In some cases, partial batches may emit both the payload and the error envelope (refer to ERRORS.md for detailed behavior).

The Beads system revolves around four core entities that track work and its history:

• Issue: The primary work item containing fields like title, description, status, priority, and type.
• Dependency: Directed edges between issues (e.g., blocks, parent-child, or related).
• Label: Arbitrary tags used for categorization.
• Event: An audit trail recording all changes, such as status transitions or field updates.

Status Workflow: open → in_progress → blocked → closed
(Note: blocked can transition to deferred, which can later return to open.)

Priority Levels: P0 (critical) → P1 (high) → P2 (medium) → P3 (low) → P4 (backlog)

Issue Types: task, bug, feature, epic, chore, docs, question

The br CLI uses a unified OutputHandler to manage how data is presented to users or machines. This ensures consistent behavior across all commands.

Supported Formats:

• Text (Default): Human-readable output. Uses ANSI colors unless --no-color is set or the NO_COLOR environment variable is present. If --robot mode is active, it uses to_robot_text() for deterministic, non-decorative output.
• JSON: Pretty-printed JSON objects.
• JSONL: Line-delimited JSON (one object per line), ideal for streaming or appending to logs.
• Compact: Single-line, non-pretty JSON.

Error Output: Errors are always sent to stderr. If the output format is set to JSON, errors are emitted as a JSON object containing the error message and a suggestion:

{
  "error": "error message",
  "suggestion": "hint for the user"
}

The following invariants must be enforced by the application logic or SQLite CHECK constraints to ensure data integrity:

• Closed-At Invariant: If status is "closed", closed_at MUST be set. If status is NOT in ("closed", "tombstone"), closed_at MUST be NULL.
• Tombstone Invariant: If status is "tombstone", deleted_at MUST be set. Otherwise, deleted_at SHOULD be NULL.
• Priority Range: 0 <= priority <= 4.
• Title Length: 1 <= len(title) <= 500.
• Cycle Prevention: Blocking dependencies (blocks, parent-child, conditional-blocks, waits-for) cannot form cycles. This must be checked before insertion.
• ID Uniqueness: All issue IDs must be unique (Primary Key).
• External Ref Uniqueness: All non-NULL external_ref values must be unique (Unique Index).

The beads_rust workspace health is classified into four levels. This classification determines which operations are permitted on the workspace:

• Healthy: All invariants hold. All operations are allowed.
• Degraded: Derived state is stale or minor drift exists. All operations are allowed, but with advisory warnings.
• Recoverable: Primary data is intact, but the database is corrupted. The workspace is Read-only until recovery is performed.
• Unsafe: Interchange data (JSONL) is corrupted beyond repair. No operations are allowed until a manual fix is applied.

Severity Escalation Rule: Composite health is determined by the maximum individual severity found. For example, if one component is Recoverable, the entire workspace is Recoverable even if all other components are Healthy.