beads/internal/storage/embeddeddolt/transaction.go
Julian Knutsen d801ec43dc
feat(issueops): put every issue capability behind one library surface
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.

Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.

A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.

Behaviour users will notice, all in the CHANGELOG:
  - bd close a b c is one Dolt commit, not three, and --claim-next moved
    inside that transaction so it fires only when something landed
  - the open-children guard moved into the transaction and its hand-rolled
    cmd/bd copy is gone, removing a read-then-write window that made
    bd close <child> <parent> depend on argument order
  - bd dep add --file honours deferred version commit
  - embedded bd comment writes the role's message and author
  - dep verb commit messages are the role's on the direct route

Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.

Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.

Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.

Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 12:27:56 -07:00

380 lines
16 KiB
Go

//go:build cgo
package embeddeddolt
import (
"context"
"database/sql"
"fmt"
"time"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/storage/versioncontrolops"
"github.com/steveyegge/beads/internal/types"
)
// RunInTransaction executes a function within a database transaction.
// After the SQL transaction commits, dirty tables are selectively staged
// and a Dolt version commit is created with the given message.
func (s *EmbeddedDoltStore) RunInTransaction(ctx context.Context, commitMsg string, fn func(tx storage.Transaction) error) error {
return s.runTransaction(ctx, commitMsg, func(tx *embeddedTransaction) error { return fn(tx) })
}
// RunInIssueLifecycleTransaction keeps lifecycle work on the embedded store's
// one transaction and stages only durable rows changed by that work.
func (s *EmbeddedDoltStore) RunInIssueLifecycleTransaction(ctx context.Context, commitMsg string, fn func(tx storage.IssueLifecycleTransaction) error) error {
return s.runTransaction(ctx, commitMsg, func(tx *embeddedTransaction) error { return fn(tx) })
}
func (s *EmbeddedDoltStore) runTransaction(ctx context.Context, commitMsg string, fn func(tx *embeddedTransaction) error) error {
return s.runTransactionWithMessage(ctx, func(tx *embeddedTransaction) (string, error) {
return commitMsg, fn(tx)
})
}
// runTransactionWithMessage is runTransaction for work whose commit message is
// only known once the body has run. A ready claim names the id it won, and
// nothing outside the transaction can predict which one that is.
func (s *EmbeddedDoltStore) runTransactionWithMessage(ctx context.Context, fn func(tx *embeddedTransaction) (string, error)) error {
var tracker versioncontrolops.DirtyTableTracker
var commitMsg string
if err := s.withConn(ctx, true, func(tx *sql.Tx) error {
var err error
commitMsg, err = fn(&embeddedTransaction{tx: tx, dirty: &tracker})
return err
}); err != nil {
return err
}
// Create a Dolt version commit from the working set changes.
if commitMsg != "" && len(tracker.DirtyTables()) > 0 {
return s.withMutatingDBConn(ctx, func(db versioncontrolops.DBConn) error {
return versioncontrolops.StageAndCommit(ctx, db, tracker.DirtyTables(), commitMsg, commitAuthor)
})
}
return nil
}
type embeddedTransaction struct {
tx *sql.Tx
dirty *versioncontrolops.DirtyTableTracker
}
func (t *embeddedTransaction) CreateIssue(ctx context.Context, issue *types.Issue, actor string) error {
bc, err := issueops.NewBatchContext(ctx, t.tx, storage.BatchCreateOptions{SkipPrefixValidation: true})
if err != nil {
return err
}
result, err := issueops.CreateIssueInTxWithResult(ctx, t.tx, bc, issue, actor)
if err != nil {
return err
}
for table := range issueops.CreateIssueDirtyTables(ctx, issue, result) {
t.dirty.MarkDirty(table)
}
return nil
}
func (t *embeddedTransaction) CreateIssues(ctx context.Context, issues []*types.Issue, actor string) error {
result, err := issueops.CreateIssuesInTxWithResult(ctx, t.tx, issues, actor, storage.BatchCreateOptions{
OrphanHandling: storage.OrphanAllow,
SkipPrefixValidation: true,
})
if err != nil {
return err
}
for table := range issueops.CreateIssuesDirtyTables(ctx, issues, result) {
t.dirty.MarkDirty(table)
}
return nil
}
func (t *embeddedTransaction) UpdateIssue(ctx context.Context, id string, updates map[string]interface{}, actor string) error {
issueTable, _, eventTable, _ := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, id))
result, err := issueops.UpdateIssueInTx(ctx, t.tx, id, updates, actor)
if err != nil {
return err
}
if !result.Changed {
return nil
}
t.dirty.MarkDirty(issueTable)
t.dirty.MarkDirty(eventTable)
return nil
}
func (t *embeddedTransaction) CloseIssue(ctx context.Context, id string, reason string, actor string, session string) error {
issueTable, _, eventTable, _ := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, id))
result, err := issueops.CloseIssueInTx(ctx, t.tx, id, reason, actor, session)
if err != nil || result.AlreadyClosed {
return err
}
t.dirty.MarkDirty(issueTable)
t.dirty.MarkDirty(eventTable)
if result.IssueRowsChanged {
t.dirty.MarkDirty("issues")
}
return nil
}
// ReopenIssueWithResult lets transaction-scoped callers preserve lifecycle
// semantics when an update crosses the done boundary.
func (t *embeddedTransaction) ReopenIssueWithResult(ctx context.Context, id string, reason string, actor string) (bool, error) {
issueTable, _, eventTable, _ := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, id))
result, err := issueops.ReopenIssueInTx(ctx, t.tx, id, reason, actor)
if err != nil {
return false, err
}
if result.Changed {
t.dirty.MarkDirty(issueTable)
t.dirty.MarkDirty(eventTable)
if result.IssueRowsChanged {
t.dirty.MarkDirty("issues")
}
}
return result.Changed, nil
}
func (t *embeddedTransaction) DeleteIssue(ctx context.Context, id string) error {
// Shared with the dolt path so the two cannot drift again; the hand-listed
// set here previously omitted child_counters and the snapshot tables, which
// the cascade also empties.
for _, cascaded := range issueops.DeleteCascadeTables(issueops.IsActiveWispInTx(ctx, t.tx, id)) {
t.dirty.MarkDirty(cascaded)
}
return issueops.DeleteIssueInTx(ctx, t.tx, id)
}
func (t *embeddedTransaction) GetIssue(ctx context.Context, id string) (*types.Issue, error) {
return issueops.GetIssueInTx(ctx, t.tx, id)
}
func (t *embeddedTransaction) SearchIssues(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error) {
return issueops.SearchIssuesInTx(ctx, t.tx, query, filter)
}
// SearchIssueIDs returns matching IDs only via issueops.SearchIssueIDsInTx.
func (t *embeddedTransaction) SearchIssueIDs(ctx context.Context, query string, filter types.IssueFilter) ([]string, error) {
return issueops.SearchIssueIDsInTx(ctx, t.tx, query, filter)
}
func (t *embeddedTransaction) AddDependency(ctx context.Context, dep *types.Dependency, actor string) error {
return t.AddDependencyWithOptions(ctx, dep, actor, storage.DependencyAddOptions{})
}
func (t *embeddedTransaction) AddDependencyWithOptions(ctx context.Context, dep *types.Dependency, actor string, addOpts storage.DependencyAddOptions) error {
_, _, eventTable, depTable := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, dep.IssueID))
eventWritten, err := issueops.AddDependencyInTx(ctx, t.tx, dep, actor, issueops.AddDependencyOpts{
IsCrossPrefix: types.ExtractPrefix(dep.IssueID) != types.ExtractPrefix(dep.DependsOnID),
SkipCycleCheck: addOpts.SkipCycleCheck,
EmitEvent: addOpts.EmitEvent,
})
if err != nil {
return err
}
t.dirty.MarkDirty(depTable)
// AddDependencyInTx records a dependency_added event on the source's event
// table only for a genuine emit (explicit verb + new edge); stage it so the
// event commits with the edge. A structural or idempotent add writes no event.
if eventWritten {
t.dirty.MarkDirty(eventTable)
}
return nil
}
// CycleThroughEdges reports a scheduling cycle through one of the new edges,
// including the transaction's own uncommitted dependency writes
// (bd-6dnrw.8, bd-578h9.9).
func (t *embeddedTransaction) CycleThroughEdges(ctx context.Context, edges [][2]string) (string, error) {
graph := make(map[string][]string)
if err := issueops.AppendSchedulingGraphInTx(ctx, t.tx, []string{"dependencies", "wisp_dependencies"}, graph); err != nil {
return "", err
}
return issueops.CycleThroughEdgesInGraph(graph, edges), nil
}
func (t *embeddedTransaction) RemoveDependency(ctx context.Context, issueID, dependsOnID string, actor string) error {
return t.RemoveDependencyWithOptions(ctx, issueID, dependsOnID, actor, storage.DependencyRemoveOptions{})
}
func (t *embeddedTransaction) RemoveDependencyWithOptions(ctx context.Context, issueID, dependsOnID string, actor string, rmOpts storage.DependencyRemoveOptions) error {
// Route dirty marking on the source's wisp status: a wisp-source remove
// stages wisp_dependencies/wisp_events, a permanent one dependencies/events.
_, _, eventTable, depTable := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, issueID))
eventWritten, err := issueops.RemoveDependencyInTx(ctx, t.tx, issueID, dependsOnID, actor, rmOpts.EmitEvent)
if err != nil {
return err
}
t.dirty.MarkDirty(depTable)
// RemoveDependencyInTx records a dependency_removed event on the source's
// event table only for a genuine emit (explicit verb + edge removal); stage
// it so it commits with the edge. A structural or missing-edge remove writes
// no event.
if eventWritten {
t.dirty.MarkDirty(eventTable)
}
return nil
}
func (t *embeddedTransaction) GetDependencyRecords(ctx context.Context, issueID string) ([]*types.Dependency, error) {
m, err := issueops.GetDependencyRecordsForIssuesInTx(ctx, t.tx, []string{issueID})
if err != nil {
return nil, err
}
return m[issueID], nil
}
func (t *embeddedTransaction) AddLabel(ctx context.Context, issueID, label, actor string) error {
_, labelTable, eventTable, _ := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, issueID))
if err := issueops.AddLabelInTx(ctx, t.tx, labelTable, eventTable, issueID, label, actor); err != nil {
return err
}
t.dirty.MarkDirty(labelTable)
t.dirty.MarkDirty(eventTable)
return nil
}
func (t *embeddedTransaction) RemoveLabel(ctx context.Context, issueID, label, actor string) error {
_, labelTable, eventTable, _ := issueops.WispTableRouting(issueops.IsActiveWispInTx(ctx, t.tx, issueID))
if err := issueops.RemoveLabelInTx(ctx, t.tx, labelTable, eventTable, issueID, label, actor); err != nil {
return err
}
t.dirty.MarkDirty(labelTable)
t.dirty.MarkDirty(eventTable)
return nil
}
func (t *embeddedTransaction) GetLabels(ctx context.Context, issueID string) ([]string, error) {
return issueops.GetLabelsInTx(ctx, t.tx, "", issueID)
}
func (t *embeddedTransaction) SetConfig(ctx context.Context, key, value string) error {
t.dirty.MarkDirty("config")
if err := issueops.SetConfigInTx(ctx, t.tx, key, value); err != nil {
return err
}
// Sync normalized tables when config keys change
switch key {
case "status.custom":
t.dirty.MarkDirty("custom_statuses")
if err := issueops.SyncCustomStatusesTable(ctx, t.tx, value); err != nil {
return fmt.Errorf("syncing custom_statuses table: %w", err)
}
case "types.custom":
t.dirty.MarkDirty("custom_types")
if err := issueops.SyncCustomTypesTable(ctx, t.tx, value); err != nil {
return fmt.Errorf("syncing custom_types table: %w", err)
}
}
return nil
}
func (t *embeddedTransaction) GetConfig(ctx context.Context, key string) (string, error) {
return issueops.GetConfigInTx(ctx, t.tx, key)
}
func (t *embeddedTransaction) SetMetadata(ctx context.Context, key, value string) error {
t.dirty.MarkDirty("metadata")
return issueops.SetMetadataInTx(ctx, t.tx, key, value)
}
func (t *embeddedTransaction) GetMetadata(ctx context.Context, key string) (string, error) {
return issueops.GetMetadataInTx(ctx, t.tx, key)
}
func (t *embeddedTransaction) SetLocalMetadata(ctx context.Context, key, value string) error {
return issueops.SetLocalMetadataInTx(ctx, t.tx, key, value)
}
func (t *embeddedTransaction) GetLocalMetadata(ctx context.Context, key string) (string, error) {
return issueops.GetLocalMetadataInTx(ctx, t.tx, key)
}
func (t *embeddedTransaction) AddComment(ctx context.Context, issueID, actor, comment string) error {
return fmt.Errorf("embeddedTransaction: AddComment not implemented")
}
func (t *embeddedTransaction) ImportIssueComment(ctx context.Context, issueID, author, text string, createdAt time.Time) (*types.Comment, error) {
return nil, fmt.Errorf("embeddedTransaction: ImportIssueComment not implemented")
}
func (t *embeddedTransaction) GetIssueComments(ctx context.Context, issueID string) ([]*types.Comment, error) {
return nil, fmt.Errorf("embeddedTransaction: GetIssueComments not implemented")
}
func (t *embeddedTransaction) CreateIssueImport(ctx context.Context, issue *types.Issue, actor string, skipPrefixValidation bool) error {
bc, err := issueops.NewBatchContext(ctx, t.tx, storage.BatchCreateOptions{SkipPrefixValidation: skipPrefixValidation})
if err != nil {
return err
}
result, err := issueops.CreateIssueInTxWithResult(ctx, t.tx, bc, issue, actor)
if err != nil {
return err
}
for table := range issueops.CreateIssueDirtyTables(ctx, issue, result) {
t.dirty.MarkDirty(table)
}
return nil
}
// The composite-view reads below all run on the single embedded transaction
// handle. Unlike the classic Dolt store, the embedded store has no durable/wisp
// session split, so every read here — including the both-tiers-spanning ones —
// is read-your-writes on both tiers; the InTx functions do their own wisp
// routing on the one handle. The two-session wisp caveat in the
// storage.Transaction doc applies only to the server (Dolt) backend.
// GetIssueCommentsPage returns one keyset page of an issue's comments within the
// transaction. Mirrors EmbeddedDoltStore.GetIssueCommentsPage's issueops
// delegation.
func (t *embeddedTransaction) GetIssueCommentsPage(ctx context.Context, issueID string, after storage.CommentPageCursor, limit int) ([]*types.Comment, error) {
return issueops.GetIssueCommentsPageInTx(ctx, t.tx, issueID, after, limit)
}
// CountIssuesByGroup returns per-group issue counts within the transaction.
// Mirrors EmbeddedDoltStore.CountIssuesByGroup's issueops delegation.
func (t *embeddedTransaction) CountIssuesByGroup(ctx context.Context, filter types.IssueFilter, groupBy string) (map[string]int, error) {
return issueops.CountIssuesByGroupInTx(ctx, t.tx, filter, groupBy)
}
// GetDependentRecords returns the raw inbound dependency rows of targetID within
// the transaction. Mirrors EmbeddedDoltStore.GetDependentRecords; the InTx
// function spans both dependency tables itself.
func (t *embeddedTransaction) GetDependentRecords(ctx context.Context, targetID string, depType string, limit int, afterID string) ([]*types.Dependency, error) {
return issueops.GetDependentRecordsInTx(ctx, t.tx, targetID, depType, limit, afterID)
}
// GetDependentRecordsForIssues returns the raw inbound dependency rows for a set
// of target ids within the transaction, keyed by target id. Mirrors
// EmbeddedDoltStore.GetDependentRecordsForIssues.
func (t *embeddedTransaction) GetDependentRecordsForIssues(ctx context.Context, targetIDs []string) (map[string][]*types.Dependency, error) {
return issueops.GetDependentRecordsForIssuesInTx(ctx, t.tx, targetIDs)
}
// CountDependentRecords returns the total inbound-edge count of targetID within
// the transaction. Mirrors EmbeddedDoltStore.CountDependentRecords.
func (t *embeddedTransaction) CountDependentRecords(ctx context.Context, targetID string, depType string) (int, error) {
return issueops.CountDependentRecordsInTx(ctx, t.tx, targetID, depType)
}
// IsBlocked reports the denormalized transitive is_blocked flag and direct
// blockers of issueID within the transaction. Mirrors
// EmbeddedDoltStore.IsBlocked's issueops delegation.
func (t *embeddedTransaction) IsBlocked(ctx context.Context, issueID string) (bool, []string, error) {
return issueops.IsBlockedInTx(ctx, t.tx, issueID)
}
// IsBlockedBatch reports the denormalized transitive is_blocked flag for a page
// of ids within the transaction. Mirrors EmbeddedDoltStore.IsBlockedBatch; the
// InTx function batches over both the issues and wisps tables itself.
func (t *embeddedTransaction) IsBlockedBatch(ctx context.Context, ids []string) (map[string]bool, error) {
return issueops.IsBlockedBatchInTx(ctx, t.tx, ids)
}
// EventsSince returns durable events strictly after the keyset cursor within the
// transaction. Mirrors EmbeddedDoltStore.EventsSince's issueops delegation.
func (t *embeddedTransaction) EventsSince(ctx context.Context, cursor storage.EventCursor, issueID string, limit int) ([]*types.Event, error) {
return issueops.EventsSinceInTx(ctx, t.tx, cursor.CreatedAt, cursor.ID, issueID, limit)
}