Follow-up to 1ce765ee (UUID primary keys for federation-safe events).
The core migration changed types and schema, but many files still
referenced the old AUTO_INCREMENT design. This commit makes the
codebase internally consistent:
- Update embedded Dolt schema SQL files to use CHAR(36) UUID PKs
- Fix backup restore: json.Number -> string for UUID event/comment IDs
(fixes TestBackupRestoreRoundTrip)
- Remove dead LastEventID field from backup state (never set)
- Update comments in issueops/create.go, import test, git_remote_test
- Update docs/audit-sync-mode-complexity.md (mark auto-increment resolved)
- Update version history in info.go
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
174 lines
9.3 KiB
Markdown
174 lines
9.3 KiB
Markdown
# Audit: Sync Mode Complexity in Beads
|
|
|
|
**Wanted Item:** w-bd-004
|
|
**Date:** 2026-03-04
|
|
**Status:** Audit complete
|
|
|
|
## Executive Summary
|
|
|
|
Beads' sync subsystem has been significantly simplified through recent refactoring (v0.50-v0.53). The old multi-mode architecture (git-portable, belt-and-suspenders, dolt-native) has been collapsed to a single mode: **dolt-native**. However, vestigial configuration scaffolding and unnecessary abstraction layers remain. This audit identifies remaining complexity and recommends further simplifications.
|
|
|
|
## Current Architecture
|
|
|
|
### Sync Mode Configuration (Vestigial)
|
|
|
|
**File:** `internal/config/sync.go`
|
|
|
|
The `SyncMode` type, validation functions, and config plumbing still exist despite there being only one valid mode:
|
|
|
|
```go
|
|
type SyncMode string
|
|
const SyncModeDoltNative SyncMode = "dolt-native"
|
|
|
|
var validSyncModes = map[SyncMode]bool{
|
|
SyncModeDoltNative: true,
|
|
}
|
|
```
|
|
|
|
`GetSyncMode()` is hardcoded to return `SyncModeDoltNative` regardless of configuration. Yet the infrastructure around it persists:
|
|
|
|
- `SyncMode` type definition and `String()` method
|
|
- `validSyncModes` map (1 entry)
|
|
- `ValidSyncModes()` function (returns 1-element slice)
|
|
- `IsValidSyncMode()` validation function
|
|
- `SyncConfig` struct in `config.go` with `Mode` field
|
|
- `GetSyncConfig()` that calls `GetSyncMode()`
|
|
- Config default: `v.SetDefault("sync.mode", SyncModeDoltNative)`
|
|
- Config validation in `cmd/bd/config.go` that checks `sync.mode` is valid
|
|
- Tests for all of the above (`sync_test.go`: 6 test functions)
|
|
|
|
**Recommendation: Remove.** Since there is only one mode and `GetSyncMode()` is hardcoded, all SyncMode machinery is dead weight. Any code that checks the sync mode can be simplified to unconditional dolt-native behavior.
|
|
|
|
### Export/Import Trigger Configuration
|
|
|
|
**File:** `internal/config/config.go` (lines 157-158)
|
|
|
|
```go
|
|
v.SetDefault("sync.export_on", SyncTriggerPush) // push | change
|
|
v.SetDefault("sync.import_on", SyncTriggerPull) // pull | change
|
|
```
|
|
|
|
These config keys (`sync.export_on`, `sync.import_on`) still exist with two trigger values each (`push`/`change` for export, `pull`/`change` for import). They are read into `SyncConfig` via `GetSyncConfig()`.
|
|
|
|
**Assessment:** These triggers remain meaningful for controlling when Dolt sync operations fire. However, since `bd sync` was removed (v0.51+, replaced by `bd dolt push`/`bd dolt pull`), and Dolt handles persistence directly, it is worth verifying whether these triggers are still consumed by any runtime code path. If they are only used in the hook system (`internal/hooks/`), they may still be relevant. If not, they are dead config.
|
|
|
|
**Recommendation: Audit callers.** If `sync.export_on` and `sync.import_on` have no runtime consumers, remove them. If they are consumed, document which code paths use them.
|
|
|
|
### Push/Pull Routing Complexity (Justified)
|
|
|
|
**File:** `internal/storage/dolt/store.go` (lines 1351-1462)
|
|
|
|
Each of `Push()`, `ForcePush()`, and `Pull()` has a 3-way routing decision:
|
|
|
|
1. **Git-protocol remote** (SSH, git+https://) -> shell out to `dolt push/pull` CLI
|
|
2. **Hosted Dolt with remoteUser** -> `CALL DOLT_PUSH('--user', ...)` via SQL
|
|
3. **Default** (DoltHub, S3, GCS, file) -> `CALL DOLT_PUSH(?, ?)` via SQL
|
|
|
|
This produces significant code duplication. Each method repeats the same pattern:
|
|
```go
|
|
if s.isGitProtocolRemote(ctx) { ... CLI path ... }
|
|
if s.remoteUser != "" { ... SQL with --user ... }
|
|
// default SQL path
|
|
```
|
|
|
|
**Assessment:** This routing is necessary -- the three paths exist because Dolt has genuinely different authentication mechanisms. The comments explain why git-protocol remotes cannot use the SQL connection (MySQL connection timeouts during transfer). This is **justified complexity**.
|
|
|
|
**Recommendation: Extract a helper.** The 3-way dispatch pattern could be extracted into a single `execDoltRemoteOp` helper that takes the operation (push/pull/fetch), force flag, and CLI args. This would eliminate ~50 lines of duplication across Push/ForcePush/Pull without changing semantics. However, this is a minor refactor and not urgent.
|
|
|
|
### Federation Peer System (Active, Well-Structured)
|
|
|
|
**File:** `internal/storage/dolt/federation.go` (340 lines)
|
|
**File:** `internal/storage/dolt/credentials.go` (473 lines)
|
|
|
|
The federation subsystem provides:
|
|
- Peer-to-peer sync: `Sync()`, `PushTo()`, `PullFrom()`, `Fetch()`
|
|
- Credential management: AES-GCM encryption, key migration, peer CRUD
|
|
- Sync status tracking: ahead/behind counts, conflict detection
|
|
- CLI/SQL routing: same `isPeerGitProtocolRemote` pattern as main Push/Pull
|
|
|
|
The `Sync()` method (federation.go:186-256) orchestrates a 5-step bidirectional sync: fetch, get-status, merge, resolve-conflicts, push. This is straightforward and well-commented.
|
|
|
|
**Assessment:** This is active, well-structured code. The credential encryption with key migration (legacy SHA-256-derived key to random AES-256 key) is solid. The `withPeerCredentials` / `withEnvCredentials` pattern cleanly separates CLI-subprocess isolation from SQL-path mutex protection.
|
|
|
|
**Recommendation: No changes needed.** This is appropriate complexity for federation.
|
|
|
|
### Conflict Resolution Configuration (Active, Clean)
|
|
|
|
**File:** `internal/config/sync.go` (lines 53-125)
|
|
|
|
Four conflict strategies (`newest`, `ours`, `theirs`, `manual`) and four field-level strategies (`newest`, `max`, `union`, `manual`) are well-defined with validation. These are actively used by the federation `Sync()` method for auto-resolution.
|
|
|
|
**Assessment:** Clean, well-tested, appropriate complexity.
|
|
|
|
**Recommendation: No changes needed.**
|
|
|
|
### Sovereignty Tiers (Active, Clean)
|
|
|
|
**File:** `internal/config/sync.go` (lines 127-168)
|
|
|
|
Four sovereignty tiers (T1-T4) for federation access control. Used in `FederationPeer.Sovereignty`.
|
|
|
|
**Assessment:** Small, well-defined, appropriately simple.
|
|
|
|
**Recommendation: No changes needed.**
|
|
|
|
### Tracker SyncEngine (Active, Good Abstraction)
|
|
|
|
**File:** `internal/tracker/engine.go`
|
|
|
|
A shared sync engine for external trackers (Linear, GitLab, Jira) with `PullHooks`/`PushHooks` for customization. This replaced ~800 lines of duplicated sync code (v0.50.3 changelog).
|
|
|
|
**Assessment:** Good abstraction that unified three parallel implementations. Not part of the Dolt sync path -- this is for external issue tracker bidirectional sync.
|
|
|
|
**Recommendation: No changes needed.** This is separate from Dolt sync mode and is already well-factored.
|
|
|
|
### Auto-Increment Reset After Pull (Resolved)
|
|
|
|
**Status:** Resolved in v0.60+ by migrating to UUID primary keys.
|
|
|
|
The `resetAutoIncrements()` workaround was removed when all six affected tables
|
|
(events, comments, issue_snapshots, compaction_snapshots, wisp_events,
|
|
wisp_comments) were migrated from `BIGINT AUTO_INCREMENT` to `CHAR(36) UUID()`
|
|
primary keys. UUID PKs eliminate counter collisions in multi-clone federation.
|
|
|
|
## Summary of Recommendations
|
|
|
|
| Area | Recommendation | Effort | Impact |
|
|
|------|---------------|--------|--------|
|
|
| SyncMode type + validation | **Remove entirely** | Small | Removes ~80 lines of dead code + ~100 lines of tests |
|
|
| `sync.mode` config key | **Remove** (keep only as deprecated no-op) | Small | Simplifies config validation |
|
|
| `sync.export_on`/`sync.import_on` | **Audit callers**, remove if dead | Small | Removes dead config or documents live usage |
|
|
| Push/Pull/ForcePush 3-way routing | **Extract helper** (optional) | Medium | ~50 lines deduplication |
|
|
| Federation peer system | **No change** | - | Already clean |
|
|
| Conflict/field strategies | **No change** | - | Already clean |
|
|
| Sovereignty tiers | **No change** | - | Already clean |
|
|
| Tracker SyncEngine | **No change** | - | Already clean |
|
|
| Auto-increment reset | **Resolved** — removed via UUID PK migration | - | Done |
|
|
|
|
## Files Analyzed
|
|
|
|
| File | Lines | Role |
|
|
|------|-------|------|
|
|
| `internal/config/sync.go` | 240 | Sync mode, conflict, sovereignty, field strategy types |
|
|
| `internal/config/sync_test.go` | 436 | Tests for all sync config types |
|
|
| `internal/config/config.go` | 921 | Config initialization, defaults, SyncConfig/ConflictConfig structs |
|
|
| `internal/config/yaml_config.go` | ~300 | YAML config management, yaml-only keys |
|
|
| `internal/storage/dolt/store.go` | 1668 | DoltStore: Push, Pull, ForcePush |
|
|
| `internal/storage/dolt/federation.go` | 340 | Federation sync: Sync, PushTo, PullFrom, Fetch |
|
|
| `internal/storage/dolt/credentials.go` | 473 | Federation peer credentials, encryption |
|
|
| `internal/storage/versioned.go` | 60 | Shared types: Conflict, SyncStatus, FederationPeer |
|
|
| `internal/tracker/engine.go` | ~200 | External tracker SyncEngine |
|
|
| `internal/hooks/hooks.go` | ~100 | Hook runner (create/update/close events) |
|
|
| `cmd/bd/config.go` | ~500 | CLI config commands, sync.mode validation |
|
|
| `cmd/bd/info.go` | ~400 | Version history documenting sync removals |
|
|
|
|
## Historical Context
|
|
|
|
The sync subsystem has undergone major simplification across v0.50-v0.53:
|
|
|
|
- **v0.50.3**: Tracker sync code unified via shared SyncEngine (~800 lines removed)
|
|
- **v0.51.0**: SQLite backend, JSONL sync, 3-way merge, tombstones, storage factory, daemon stubs removed. `bd sync` removed (replaced by `bd dolt push`/`bd dolt pull`).
|
|
- **v0.52.0**: Dead git-portable sync functions removed (#1793)
|
|
- **v0.53.0**: JSONL sync-branch pipeline removed (~11,000 lines). Daemon infrastructure and 3-way merge remnants removed.
|
|
|
|
The remaining SyncMode scaffolding is the last vestige of the old multi-mode era and can be safely removed.
|