fix(defer): auto-wake expired dated defers on ready-front reads and claims (bd-i8qx8) (#5386)

* fix(defer): auto-wake expired dated defers on ready-front reads and claims (bd-i8qx8)

A dated defer (bd defer --until / bd update --defer) sets status=deferred
plus defer_until, but nothing ever flipped the status back — the ready
WHERE clause's defer_until predicate only helps rows already 'open', so an
expired defer stayed invisible to bd ready forever until a human ran bd
undefer. One deployment measured 241 issues (24 P1s in the first census)
silently dark this way, regenerating ~11/day from correct-looking
automation ('needs-design cooldown' call sites that defer +7d).

Fix: a lazy wake sweep (issueops.WakeExpiredDefersInTx, one shared DBTX
body serving both storage stacks, shaped after ReclaimExpiredLeasesInTx)
runs at the top of every ready-front read and claim:

- classic dolt server store: GetReadyWork/WithCounts/CountReadyWork and
  readyClaimer.ClaimNext, via runIssueOperationTxWithMessage in a write tx
  of its own (the read paths' withReadTx always rolls back)
- embedded store: same three seams plus its readyClaimer
- domain/uow stack (proxied CLI + bd serve): uow.WakeExpiredDefers in a
  committing UOW before Reader.Ready, Reader.List(--ready), the proxied
  CLI ready route, and uow readyClaimer.ClaimNext

Waking writes status=open, defer_until=NULL — byte-identical to bd
undefer, so a later dateless re-defer cannot inherit a stale past date —
and records a status_changed event (actor bd-defer-wake). A DATELESS
defer never auto-wakes: it is the indefinite icebox, and bd undefer stays
its only exit. The sweep is RowsAffected-gated (zero matches ⇒ no dolt
commit), advisory by contract (a ready listing never fails because the
sweep could not run; strict --readonly skips it), and covers wisps
(dolt_ignored, so wisp wakes mint no version commit by construction).

Tests: TestEmbeddedDeferAutoWake (wake/icebox/future/claimable) and
TestProxiedServerDeferAutoWake (parity subtest), green alongside the
existing defer/undefer/ready embedded and proxied suites.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: auto-regenerate CLI reference

Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/31145176188
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.

* fix(defer): persist wisp-only wakes in the uow stack; warn-once on access-denied (bd-i8qx8)

The uow sweep discarded wisp-only wakes: the repo returned only the
permanent-issue count, a wisp-only sweep produced commitMsg == "",
RunTxResult skipped Commit, and Close rolled the transaction back —
expired wisp defers stayed deferred forever in proxied/serve mode while
embedded mode woke them, and every ready read redid and re-discarded the
same writes. A wake commit message would not have fixed it: wisp tables
are dolt_ignored, so DOLT_COMMIT errors nothing-to-commit and the tx
still rolls back.

WakeExpiredDefers now reports (issues, wisps) through the repo and use
case; the uow sweep commits with the wake message when permanent issues
woke, and persists a wisp-only wake via uw.Commit(ctx, "") — the
ephemeral plain-COMMIT form RunTxEphemeral keeps for dolt_ignored state.
Wisp parity subtests added to both the embedded and proxied defer
auto-wake tests.

Also: dberrors.IsAccessDenied classifier + warn-once handling in both
defer-wake advisory handlers, so a read-only-privileged client gets one
warning per process instead of one per bd ready.

* ci: trigger runs for 0a94d44f4 (empty)

* test(defer): teach the ready-surface test fixtures about the wake sweep (bd-i8qx8)

Three fixtures pinned the pre-sweep ready path and broke against it:

- readerIssues and recordingIssues embed a nil domain.IssueUseCase and
  stub only the read methods, so the sweep's promoted WakeExpiredDefers
  call segfaulted (surfacing as a 500 on every httpapi ready-surface
  test). Both now stub a no-op sweep.
- The reader-parity fixture's provider pool held one unit of work; the
  ready arm now opens two (sweep, then read span), and past the pool the
  mock provider hands out zero-valued units. The pool holds both.
- TestAReadRouteTimesTheUnitsOfWorkItsReaderOpens counted exactly one
  unit of work; the count is now two, and both still land in uow_ms,
  which is the property the test exists to pin.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Steve Yegge 2026-08-07 04:34:38 -07:00 • committed by GitHub
commit 01f9166810
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 769 additions and 7 deletions

View file

@ -63,6 +63,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
disable the fallback everywhere). Explicit IDs and `bd show --current` are
unaffected.
- **A dated defer now means what it says: the issue returns to the ready front
when the date passes** (bd-i8qx8). `bd defer --until` and `bd update --defer`
set `status=deferred` plus a `defer_until` timestamp, but nothing ever
flipped the status back — so an expired defer stayed invisible to `bd ready`
forever until a human ran `bd undefer`. One deployment measured 241 issues
(including P1s) silently dark this way, regenerating daily from
correct-looking automation.
Ready-front reads and claims (`bd ready`, `bd ready --claim`, `bd list
--ready`, and the serve/proxied Reader roles) now run a lazy wake sweep
first: every issue (and wisp) with `status=deferred` and `defer_until <=
now` flips to `status=open, defer_until=NULL` — byte-identical to what `bd
undefer` writes, so a later dateless re-defer cannot inherit a stale past
date. Each wake records a `status_changed` event (actor `bd-defer-wake`).
What does NOT change: a **dateless** defer (`bd defer` with no `--until`,
`defer_until` NULL) is the indefinite icebox and never auto-wakes — `bd
undefer` remains its only exit. The sweep is a no-op when nothing has
expired (no dolt commit is minted), advisory by contract (a ready listing
never fails because the sweep could not run — strict `--readonly` skips it),
and identical in embedded, server, and proxied-server modes.
- **`bd delete --cascade` no longer marks LIVE issues as deleted in other
issues' text** (bd-x82so). When the deletion named a wisp, the set used to

View file

@ -26,9 +26,14 @@ be revisited.
Deferred issues don't show in 'bd ready' but remain visible in 'bd list'.
A defer WITH a date is a snooze: once --until passes, the next ready-front
read returns the issue to open automatically (same shape as 'bd undefer').
A defer WITHOUT a date is the indefinite icebox: it stays deferred until
someone runs 'bd undefer'.
Examples:
bd defer bd-abc # Defer a single issue (status-based)
bd defer bd-abc --until=tomorrow # Defer until specific time
bd defer bd-abc # Icebox indefinitely (until bd undefer)
bd defer bd-abc --until=tomorrow # Snooze: auto-wakes once the date passes
bd defer bd-abc --reason="waiting on API access"
bd defer bd-abc bd-def # Defer multiple issues`,
Args: cobra.MinimumNArgs(1),

View file

@ -0,0 +1,184 @@
//go:build cgo
package main
import (
"encoding/json"
"os"
"os/exec"
"strings"
"testing"
)
// showDeferState returns (status, defer_until) for an issue via bd show --json.
func showDeferState(t *testing.T, bd, dir, id string) (string, interface{}) {
t.Helper()
cmd := exec.Command(bd, "show", id, "--json")
cmd.Dir = dir
cmd.Env = bdEnv(dir)
stdout, stderr, err := runCommandBuffers(t, cmd)
if err != nil {
t.Fatalf("bd show %s --json failed: %v\nstdout:\n%s\nstderr:\n%s", id, err, stdout.String(), stderr.String())
}
s := strings.TrimSpace(stdout.String())
start := strings.IndexAny(s, "[{")
if start < 0 {
t.Fatalf("no JSON in show output: %s", s)
}
var m map[string]interface{}
if s[start] == '[' {
var arr []map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &arr); err != nil {
t.Fatalf("parse show JSON array: %v\n%s", err, s)
}
if len(arr) == 0 {
t.Fatalf("empty JSON array in show output")
}
m = arr[0]
} else {
if err := json.Unmarshal([]byte(s[start:]), &m); err != nil {
t.Fatalf("parse show JSON: %v\n%s", err, s)
}
}
status, _ := m["status"].(string)
return status, m["defer_until"]
}
// wakeReadyIDs runs bd ready --json (plus extra args) and returns the listed ids.
func wakeReadyIDs(t *testing.T, bd, dir string, args ...string) map[string]bool {
t.Helper()
fullArgs := append([]string{"ready", "--json"}, args...)
cmd := exec.Command(bd, fullArgs...)
cmd.Dir = dir
cmd.Env = bdEnv(dir)
stdout, stderr, err := runCommandBuffers(t, cmd)
if err != nil {
t.Fatalf("bd ready --json failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout.String(), stderr.String())
}
s := strings.TrimSpace(stdout.String())
start := strings.Index(s, "[")
if start < 0 {
return map[string]bool{}
}
var arr []map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &arr); err != nil {
t.Fatalf("parse ready JSON: %v\n%s", err, s)
}
ids := map[string]bool{}
for _, row := range arr {
if id, ok := row["id"].(string); ok {
ids[id] = true
}
}
return ids
}
// TestEmbeddedDeferAutoWake documents the defer contract: a DATED defer is a
// snooze — once defer_until passes, the next ready-front read returns the
// issue to open (status open, defer_until cleared, same shape bd undefer
// writes). A DATELESS defer is the indefinite icebox and never auto-wakes.
func TestEmbeddedDeferAutoWake(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "dw")
t.Run("expired_dated_defer_wakes_on_ready", func(t *testing.T) {
issue := bdCreate(t, bd, dir, "Expired snooze", "--type", "task")
// defer.go warns about a past date but proceeds: status=deferred with
// an already-expired defer_until — exactly the tomb state a defer that
// expired while nobody was looking leaves behind.
bdDefer(t, bd, dir, issue.ID, "--until", "2020-01-01")
status, _ := showDeferState(t, bd, dir, issue.ID)
if status != "deferred" {
t.Fatalf("precondition: expected status=deferred, got %q", status)
}
ids := wakeReadyIDs(t, bd, dir)
if !ids[issue.ID] {
t.Errorf("expected %s in bd ready after its defer date passed", issue.ID)
}
status, deferUntil := showDeferState(t, bd, dir, issue.ID)
if status != "open" {
t.Errorf("expected status=open after wake, got %q", status)
}
if deferUntil != nil {
t.Errorf("expected defer_until cleared after wake (undefer's shape), got %v", deferUntil)
}
})
t.Run("dateless_defer_never_wakes", func(t *testing.T) {
issue := bdCreate(t, bd, dir, "Indefinite icebox", "--type", "task")
bdDefer(t, bd, dir, issue.ID)
ids := wakeReadyIDs(t, bd, dir)
if ids[issue.ID] {
t.Errorf("dateless defer %s must not appear in bd ready", issue.ID)
}
status, _ := showDeferState(t, bd, dir, issue.ID)
if status != "deferred" {
t.Errorf("dateless defer must stay deferred, got %q", status)
}
})
t.Run("future_dated_defer_stays_hidden", func(t *testing.T) {
issue := bdCreate(t, bd, dir, "Future snooze", "--type", "task")
bdDefer(t, bd, dir, issue.ID, "--until", "+8760h")
ids := wakeReadyIDs(t, bd, dir)
if ids[issue.ID] {
t.Errorf("future defer %s must not appear in bd ready", issue.ID)
}
status, _ := showDeferState(t, bd, dir, issue.ID)
if status != "deferred" {
t.Errorf("future defer must stay deferred, got %q", status)
}
})
t.Run("expired_dated_defer_wakes_wisp", func(t *testing.T) {
// Wisps ride the same defer/wake contract through dolt_ignored tables,
// which take a different persistence path (SQL commit, no version
// commit) — the seam where the uow stack once rolled wisp wakes back.
issue := bdCreate(t, bd, dir, "Wisp snooze", "--type", "task", "--ephemeral", "--wisp-type", "heartbeat")
bdDefer(t, bd, dir, issue.ID, "--until", "2020-01-01")
status, _ := showDeferState(t, bd, dir, issue.ID)
if status != "deferred" {
t.Fatalf("precondition: expected status=deferred, got %q", status)
}
_ = wakeReadyIDs(t, bd, dir) // trigger the sweep
status, deferUntil := showDeferState(t, bd, dir, issue.ID)
if status != "open" {
t.Errorf("expected wisp status=open after wake, got %q", status)
}
if deferUntil != nil {
t.Errorf("expected wisp defer_until cleared after wake, got %v", deferUntil)
}
})
t.Run("expired_dated_defer_claimable", func(t *testing.T) {
issue := bdCreate(t, bd, dir, "Claimable after snooze", "--type", "task", "--labels", "wake-claim-test")
bdDefer(t, bd, dir, issue.ID, "--until", "2020-01-01")
// The claim path wakes before selecting, so the freshly-expired bead
// is claimable without any listing having run first.
cmd := exec.Command(bd, "ready", "--claim", "--json", "-l", "wake-claim-test")
cmd.Dir = dir
cmd.Env = bdEnv(dir)
stdout, stderr, err := runCommandBuffers(t, cmd)
if err != nil {
t.Fatalf("bd ready --claim failed: %v\nstdout:\n%s\nstderr:\n%s", err, stdout.String(), stderr.String())
}
if !strings.Contains(stdout.String(), issue.ID) {
t.Errorf("expected claim to win %s, got:\n%s", issue.ID, stdout.String())
}
status, _ := showDeferState(t, bd, dir, issue.ID)
if status != "in_progress" {
t.Errorf("expected status=in_progress after claim, got %q", status)
}
})
}

View file

@ -0,0 +1,146 @@
//go:build cgo
package main
import (
"encoding/json"
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
// TestProxiedServerDeferAutoWake is the proxied-mode parity subtest for the
// defer auto-wake sweep: a DATED defer whose date has passed returns to open
// on the next ready read, a DATELESS defer never does. Same contract, other
// execution mode — the sweep must behave identically in both.
func TestProxiedServerDeferAutoWake(t *testing.T) {
requireSharedProxiedServer(t)
t.Parallel()
bd := buildEmbeddedBD(t)
p := newSharedProxiedProject(t, bd, "dwk")
showState := func(t *testing.T, id string) (string, interface{}) {
t.Helper()
out, err := bdProxiedRun(t, bd, p.dir, "show", id, "--json")
if err != nil {
t.Fatalf("show %s: %v\n%s", id, err, out)
}
var arr []map[string]interface{}
if err := json.Unmarshal(out, &arr); err != nil {
t.Fatalf("unmarshal: %v\n%s", err, out)
}
if len(arr) == 0 {
t.Fatalf("show returned nothing for %s", id)
}
status, _ := arr[0]["status"].(string)
return status, arr[0]["defer_until"]
}
readySet := func(t *testing.T) map[string]bool {
t.Helper()
out, err := bdProxiedRun(t, bd, p.dir, "ready", "--json", "--limit", "0")
if err != nil {
t.Fatalf("ready: %v\n%s", err, out)
}
s := strings.TrimSpace(string(out))
start := strings.Index(s, "[")
if start < 0 {
return map[string]bool{}
}
var arr []map[string]interface{}
if err := json.Unmarshal([]byte(s[start:]), &arr); err != nil {
t.Fatalf("parse ready JSON: %v\n%s", err, s)
}
ids := map[string]bool{}
for _, row := range arr {
if id, ok := row["id"].(string); ok {
ids[id] = true
}
}
return ids
}
t.Run("expired_dated_defer_wakes_on_ready", func(t *testing.T) {
a := bdProxiedCreate(t, bd, p.dir, "Expired snooze proxied", "--type", "task")
if out, err := bdProxiedRun(t, bd, p.dir, "defer", a.ID, "--until", "2020-01-01"); err != nil {
t.Fatalf("defer: %v\n%s", err, out)
}
status, _ := showState(t, a.ID)
if status != string(types.StatusDeferred) {
t.Fatalf("precondition: status = %s, want deferred", status)
}
ids := readySet(t)
if !ids[a.ID] {
t.Errorf("expected %s in bd ready after its defer date passed", a.ID)
}
status, deferUntil := showState(t, a.ID)
if status != string(types.StatusOpen) {
t.Errorf("status = %s, want open after wake", status)
}
if deferUntil != nil {
t.Errorf("defer_until should be cleared after wake, got %v", deferUntil)
}
})
t.Run("expired_dated_defer_wakes_wisp", func(t *testing.T) {
// The uow stack's wisp seam: wisp tables are dolt_ignored, so a
// wisp-only sweep mints no wake commit and must persist through the
// ephemeral plain-COMMIT form instead — the path that once rolled
// wisp wakes back, leaving expired wisp defers deferred forever in
// proxied/serve mode while embedded mode woke them (parity break).
id := bdProxiedCreateSilent(t, bd, p.dir, "Wisp snooze proxied", "--type", "task", "--ephemeral", "--wisp-type", "heartbeat")
if out, err := bdProxiedRun(t, bd, p.dir, "defer", id, "--until", "2020-01-01"); err != nil {
t.Fatalf("defer wisp: %v\n%s", err, out)
}
status, _ := showState(t, id)
if status != string(types.StatusDeferred) {
t.Fatalf("precondition: wisp status = %s, want deferred", status)
}
if out, err := bdProxiedRun(t, bd, p.dir, "ready", "--json"); err != nil {
t.Fatalf("ready: %v\n%s", err, out)
}
status, deferUntil := showState(t, id)
if status != string(types.StatusOpen) {
t.Errorf("wisp status = %s, want open after wake (parity break vs embedded)", status)
}
if deferUntil != nil {
t.Errorf("wisp defer_until should be cleared after wake, got %v", deferUntil)
}
})
t.Run("dateless_defer_never_wakes", func(t *testing.T) {
a := bdProxiedCreate(t, bd, p.dir, "Indefinite icebox proxied", "--type", "task")
if out, err := bdProxiedRun(t, bd, p.dir, "defer", a.ID); err != nil {
t.Fatalf("defer: %v\n%s", err, out)
}
ids := readySet(t)
if ids[a.ID] {
t.Errorf("dateless defer %s must not appear in bd ready", a.ID)
}
status, _ := showState(t, a.ID)
if status != string(types.StatusDeferred) {
t.Errorf("dateless defer must stay deferred, got %s", status)
}
})
t.Run("future_dated_defer_stays_hidden", func(t *testing.T) {
a := bdProxiedCreate(t, bd, p.dir, "Future snooze proxied", "--type", "task")
if out, err := bdProxiedRun(t, bd, p.dir, "defer", a.ID, "--until", "+8760h"); err != nil {
t.Fatalf("defer: %v\n%s", err, out)
}
ids := readySet(t)
if ids[a.ID] {
t.Errorf("future defer %s must not appear in bd ready", a.ID)
}
status, _ := showState(t, a.ID)
if status != string(types.StatusDeferred) {
t.Errorf("future defer must stay deferred, got %s", status)
}
})
}

View file

@ -45,6 +45,12 @@ func runReadyProxiedServer(cmd *cobra.Command, ctx context.Context) error {
return runReadyProxiedClaim(ctx, in)
}
// Wake expired dated defers before the read below. The unit of work this
// route opens is read-only-by-ending (Close rolls back), so the sweep runs
// in a committing UOW of its own first; the claim route above gets the
// same sweep from its role (uow.readyClaimer.ClaimNext).
uow.WakeExpiredDefersAdvisory(ctx, uowProvider)
uw, err := uowProvider.NewUOW(ctx)
if err != nil {
return HandleErrorRespectJSON("open unit of work: %v", err)

View file

@ -985,7 +985,7 @@ func init() {
// --defer=+1h Hidden from bd ready for 1 hour
// --defer="" Clear defer (show in bd ready immediately)
updateCmd.Flags().String("due", "", "Due date/time (empty to clear). Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15")
updateCmd.Flags().String("defer", "", "Defer until date (empty to clear). Issue hidden from bd ready until then")
updateCmd.Flags().String("defer", "", "Defer until date (empty to clear). Issue hidden from bd ready until then, then auto-wakes to open")
// Gate fields (bd-z6kw)
updateCmd.Flags().String("await-id", "", "Set gate await_id (e.g., GitHub run ID for gh:run gates)")
// Ephemeral/persistent flags

View file

@ -40,6 +40,12 @@ func (f *recordingIssues) SearchIssuesWithCounts(_ context.Context, _ string, fi
return domain.SearchCountsPage{Items: f.items}, nil
}
// The ready surface's defer-wake sweep reaches this before the read; nothing
// is deferred in the fixture, so it reports a no-op sweep.
func (f *recordingIssues) WakeExpiredDefers(context.Context) (issues, wisps int, err error) {
return 0, 0, nil
}
func (f *recordingIssues) readyFilters() []types.WorkFilter {
f.mu.Lock()
defer f.mu.Unlock()
@ -345,8 +351,11 @@ func TestAReadRouteTimesTheUnitsOfWorkItsReaderOpens(t *testing.T) {
if resp := ts.get(t, "/v0/beads/ready"); resp.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want 200", resp.StatusCode)
}
if n := len(provider.openedUOWs()); n != 1 {
t.Fatalf("opened %d units of work, want 1", n)
// Two units of work, both through the wrapper: the ready surface's
// defer-wake sweep, then the read span. A reader bound to the untimed
// provider would report zero.
if n := len(provider.openedUOWs()); n != 2 {
t.Fatalf("opened %d units of work, want 2 (defer-wake sweep + read span)", n)
}
line := findLogLine(t, ts.stderr.String(), "op="+OpListReadyWork)

View file

@ -41,6 +41,31 @@ func IsTableNotExist(err error) bool {
unquotedTableMissingPattern.MatchString(s)
}
// IsAccessDenied reports whether err is a MySQL/Dolt privilege refusal: the
// connected user lacks the right to run the statement. Covers 1044
// (ER_DBACCESS_DENIED_ERROR), 1045 (ER_ACCESS_DENIED_ERROR), 1142
// (ER_TABLEACCESS_DENIED_ERROR), 1143 (ER_COLUMNACCESS_DENIED_ERROR) and
// 1227 (ER_SPECIFIC_ACCESS_DENIED_ERROR). Callers use it to classify a
// deliberately read-only-privileged client, which is a configuration, not a
// fault worth repeating warnings about.
func IsAccessDenied(err error) bool {
if err == nil {
return false
}
var mysqlErr *mysql.MySQLError
if errors.As(err, &mysqlErr) {
switch mysqlErr.Number {
case 1044, 1045, 1142, 1143, 1227:
return true
}
return false
}
s := strings.ToLower(err.Error())
return strings.Contains(s, "access denied") || strings.Contains(s, "command denied")
}
// IsMissingForeignKeyTarget reports whether err is the integrity-constraint
// violation a write hits when it references a row that does not exist: MySQL
// 1452 (ER_NO_REFERENCED_ROW_2) and its older 1216 (ER_NO_REFERENCED_ROW).

View file

@ -3,8 +3,12 @@ package dolt
import (
"context"
"database/sql"
"errors"
"fmt"
"os"
"sync"
"github.com/steveyegge/beads/internal/storage/dberrors"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
@ -43,7 +47,56 @@ func (s *DoltStore) SearchIssuesWithCounts(ctx context.Context, query string, fi
return result, err
}
// wakeExpiredDefers runs the lazy defer-wake sweep (issueops.WakeExpiredDefersInTx)
// in its own write transaction before a ready-work read. Advisory by contract:
// a ready listing must never fail because the sweep could not run, so every
// error is swallowed here — silently for the expected shapes (read-only store,
// open write circuit, closed store), with a stderr warning otherwise. It runs
// OUTSIDE the read tx below because withReadTx unconditionally rolls back (and
// may retry its body on the read-only justification).
func (s *DoltStore) wakeExpiredDefers(ctx context.Context) {
if s.readOnly {
return
}
err := s.withCircuitWrite(ctx, func(ctx context.Context) error {
return s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (issueops.ChangedTables, string, error) {
woke, err := issueops.WakeExpiredDefersInTx(ctx, tx)
if err != nil {
return nil, "", err
}
if len(woke.Issues) == 0 {
// Wisp-only wakes persist with the SQL commit but mint no
// version commit: wisp tables are dolt_ignored.
return nil, "", nil
}
tables := issueops.ChangedTables{}
tables.Add("issues", "events")
return tables, issueops.WakeDefersCommitMessage(len(woke.Issues)), nil
})
})
if err != nil && !errors.Is(err, ErrCircuitOpen) && !errors.Is(err, ErrStoreClosed) {
warnDeferWakeSweepSkipped(err)
}
}
// deferWakeAccessDeniedOnce rate-limits the access-denied advisory to one
// warning per process: a read-only-privileged SQL user hits it on every
// ready-front read, and repeating a configuration fact on each `bd ready`
// is noise, not signal.
var deferWakeAccessDeniedOnce sync.Once
func warnDeferWakeSweepSkipped(err error) {
if dberrors.IsAccessDenied(err) {
deferWakeAccessDeniedOnce.Do(func() {
fmt.Fprintf(os.Stderr, "warning: defer-wake sweep skipped (SQL user lacks write privileges; expired defers will not auto-wake from this client): %v\n", err)
})
return
}
fmt.Fprintf(os.Stderr, "warning: defer-wake sweep skipped: %v\n", err)
}
func (s *DoltStore) GetReadyWork(ctx context.Context, filter types.WorkFilter) ([]*types.Issue, error) {
s.wakeExpiredDefers(ctx)
var result []*types.Issue
err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
@ -54,6 +107,7 @@ func (s *DoltStore) GetReadyWork(ctx context.Context, filter types.WorkFilter) (
}
func (s *DoltStore) GetReadyWorkWithCounts(ctx context.Context, filter types.WorkFilter) ([]*types.IssueWithCounts, error) {
s.wakeExpiredDefers(ctx)
var result []*types.IssueWithCounts
err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error
@ -68,6 +122,7 @@ func (s *DoltStore) GetReadyWorkWithCounts(ctx context.Context, filter types.Wor
// cheap indexed COUNT(*)s instead of re-running the counts mega-query. Backs the
// storage.ReadyWorkCounter capability.
func (s *DoltStore) CountReadyWork(ctx context.Context, filter types.WorkFilter) (int, error) {
s.wakeExpiredDefers(ctx)
var n int
err := s.withReadTx(ctx, func(tx *sql.Tx) error {
var err error

View file

@ -44,6 +44,11 @@ func (c *readyClaimer) ClaimNext(ctx context.Context, request issueops.ClaimNext
return issueops.ClaimNextResult{}, err
}
// Wake expired dated defers before selecting, so a bead whose snooze just
// ended is claimable the moment its date passes. Advisory, in a write tx
// of its own: a failed sweep must not cost the claim.
c.store.wakeExpiredDefers(ctx)
// The write and its verify sit under withCircuitWrite so terminal circuit
// success is recorded once at the boundary, only after verifiedReadyClaim
// returns nil — matching the store's own ClaimReadyIssue. write is defined

View file

@ -1157,6 +1157,21 @@ func (r *issueSQLRepositoryImpl) HeartbeatIssue(ctx context.Context, id, actor s
return nil
}
// WakeExpiredDefers runs the shared lazy defer-wake body against this
// repository's runner (the same DBTX-shaped seam ReclaimExpiredLeases uses)
// and reports how many rows woke per table. The issues count decides whether
// the transaction's owner mints a dolt commit; the wisps count decides
// whether it must still issue a plain SQL commit — wisp tables are
// dolt_ignored, so a wisp-only wake mints no version commit, but a caller
// that treats it as "nothing happened" rolls the wisp writes back.
func (r *issueSQLRepositoryImpl) WakeExpiredDefers(ctx context.Context) (issues, wisps int, err error) {
out, err := issueops.WakeExpiredDefersInTx(ctx, r.runner)
if err != nil {
return 0, 0, fmt.Errorf("db: IssueSQLRepository.WakeExpiredDefers: %w", err)
}
return len(out.Issues), len(out.Wisps), nil
}
func (r *issueSQLRepositoryImpl) ReclaimExpiredLeases(ctx context.Context, olderThan time.Duration, filter types.ReclaimFilter, actor string) ([]types.ReclaimedLease, error) {
cutoff := time.Now().UTC().Add(-olderThan)
out, err := issueops.ReclaimExpiredLeasesInTx(ctx, r.runner, cutoff, filter, actor)

View file

@ -79,6 +79,7 @@ type IssueSQLRepository interface {
UnclaimIssueIfAssignee(ctx context.Context, id, actor, expectedAssignee string) error
HeartbeatIssue(ctx context.Context, id, actor string) error
ReclaimExpiredLeases(ctx context.Context, olderThan time.Duration, filter types.ReclaimFilter, actor string) ([]types.ReclaimedLease, error)
WakeExpiredDefers(ctx context.Context) (issues, wisps int, err error)
}
type CloseRowParams struct {
@ -298,6 +299,7 @@ type IssueUseCase interface {
UnclaimIfAssignee(ctx context.Context, id, actor, expectedAssignee string) error
Heartbeat(ctx context.Context, id, actor string) error
ReclaimExpiredLeases(ctx context.Context, olderThan time.Duration, filter types.ReclaimFilter, actor string) ([]types.ReclaimedLease, error)
WakeExpiredDefers(ctx context.Context) (issues, wisps int, err error)
CreateIssue(ctx context.Context, params CreateIssueParams, actor string) (CreateIssueResult, error)
CreateIssues(ctx context.Context, params []CreateIssueParams, actor string) (CreateIssuesResult, error)
@ -1860,6 +1862,20 @@ func (u *issueUseCaseImpl) Heartbeat(ctx context.Context, id, actor string) erro
return nil
}
// WakeExpiredDefers returns every expired DATED defer to open (see
// issueops.WakeExpiredDefersInTx) and reports how many permanent issues and
// wisps woke. The caller owns persistence: commit with a wake message iff
// issues > 0, and with the ephemeral plain-COMMIT form iff only wisps woke
// (wisp tables are dolt_ignored, so their wake needs a SQL commit but must
// mint no version commit).
func (u *issueUseCaseImpl) WakeExpiredDefers(ctx context.Context) (issues, wisps int, err error) {
issues, wisps, err = u.issueRepo.WakeExpiredDefers(ctx)
if err != nil {
return 0, 0, fmt.Errorf("WakeExpiredDefers: %w", err)
}
return issues, wisps, nil
}
func (u *issueUseCaseImpl) ReclaimExpiredLeases(ctx context.Context, olderThan time.Duration, filter types.ReclaimFilter, actor string) ([]types.ReclaimedLease, error) {
out, err := u.issueRepo.ReclaimExpiredLeases(ctx, olderThan, filter, actor)
if err != nil {

View file

@ -5,12 +5,43 @@ package embeddeddolt
import (
"context"
"database/sql"
"errors"
"fmt"
"os"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// wakeExpiredDefers runs the lazy defer-wake sweep (issueops.WakeExpiredDefersInTx)
// in its own write transaction before a ready-work read. Advisory by contract:
// a ready listing must never fail because the sweep could not run — strict
// --readonly stores skip it silently (the one mode that reaches ErrReadOnly,
// mirroring the tip-metadata write's tolerance), anything else warns. It runs
// OUTSIDE the read connections below because withConn(ctx, false, …) always
// rolls back.
func (s *EmbeddedDoltStore) wakeExpiredDefers(ctx context.Context) {
err := s.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (issueops.ChangedTables, string, error) {
woke, err := issueops.WakeExpiredDefersInTx(ctx, tx)
if err != nil {
return nil, "", err
}
if len(woke.Issues) == 0 {
// Wisp-only wakes persist with the SQL commit but mint no version
// commit: wisp tables are dolt_ignored.
return nil, "", nil
}
tables := issueops.ChangedTables{}
tables.Add("issues", "events")
return tables, issueops.WakeDefersCommitMessage(len(woke.Issues)), nil
})
if err != nil && !errors.Is(err, ErrReadOnly) {
fmt.Fprintf(os.Stderr, "warning: defer-wake sweep skipped: %v\n", err)
}
}
func (s *EmbeddedDoltStore) GetReadyWork(ctx context.Context, filter types.WorkFilter) ([]*types.Issue, error) {
s.wakeExpiredDefers(ctx)
var result []*types.Issue
err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
@ -21,6 +52,7 @@ func (s *EmbeddedDoltStore) GetReadyWork(ctx context.Context, filter types.WorkF
}
func (s *EmbeddedDoltStore) GetReadyWorkWithCounts(ctx context.Context, filter types.WorkFilter) ([]*types.IssueWithCounts, error) {
s.wakeExpiredDefers(ctx)
var result []*types.IssueWithCounts
err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error
@ -35,6 +67,7 @@ func (s *EmbeddedDoltStore) GetReadyWorkWithCounts(ctx context.Context, filter t
// cheap indexed COUNT(*)s instead of re-running the counts mega-query. Backs the
// storage.ReadyWorkCounter capability.
func (s *EmbeddedDoltStore) CountReadyWork(ctx context.Context, filter types.WorkFilter) (int, error) {
s.wakeExpiredDefers(ctx)
var n int
err := s.withConn(ctx, false, func(tx *sql.Tx) error {
var err error

View file

@ -40,6 +40,11 @@ func (c *readyClaimer) ClaimNext(ctx context.Context, request issueops.ClaimNext
return issueops.ClaimNextResult{}, err
}
// Wake expired dated defers before selecting, so a bead whose snooze just
// ended is claimable the moment its date passes. Advisory, in a write tx
// of its own: a failed sweep must not cost the claim.
c.store.wakeExpiredDefers(ctx)
var result issueops.ClaimNextResult
err = c.store.runIssueOperationTxWithMessage(ctx, func(tx *sql.Tx) (storageissueops.ChangedTables, string, error) {
attempt, tables, err := storageissueops.ExecuteClaimNext(ctx, tx, request.Actor, filter)

View file

@ -0,0 +1,138 @@
package issueops
import (
"context"
"fmt"
"time"
"github.com/steveyegge/beads/internal/storage/dberrors"
"github.com/steveyegge/beads/internal/types"
)
// DeferWakeActor is the actor recorded on the status_changed event when the
// wake sweep returns an expired dated defer to open. A constant rather than
// the invoking session's actor: the wake is the system honoring the defer
// date, not something the reader who happened to trigger it did.
const DeferWakeActor = "bd-defer-wake"
// WakeDefersResult reports what one sweep woke, per table.
type WakeDefersResult struct {
// Issues are the permanent-table issue ids returned to open; only these
// affect Dolt-versioned tables, so only these decide whether the caller
// mints a dolt commit.
Issues []string
// Wisps are the woken wisp ids. Wisp tables are dolt_ignored, so a
// wisp-only wake never needs a version commit.
Wisps []string
}
// WakeDefersCommitMessage names a sweep's dolt commit. n is the number of
// permanent issues woken (len(result.Issues)); callers with n == 0 should not
// commit at all.
func WakeDefersCommitMessage(n int) string {
return fmt.Sprintf("bd: wake %d expired defer(s)", n)
}
// WakeExpiredDefersInTx returns every DATED defer whose date has passed to
// open: status='deferred' AND defer_until <= now flips to status='open',
// defer_until=NULL — byte-identical to what `bd undefer` writes, so a later
// dateless `bd defer` cannot inherit a stale past date and instantly re-wake.
// A DATELESS defer (defer_until IS NULL) is the indefinite icebox and is
// deliberately never touched: `bd undefer` stays its only exit.
//
// This is the lazy half of the defer contract. `bd defer --until` and
// `bd update --defer` promise "hidden until <date>", but nothing ever flipped
// the status back, so an expired defer stayed invisible to the ready front
// forever. Callers run this sweep at the top of ready-work reads and claims;
// the snapshot-then-recheck shape mirrors ReclaimExpiredLeasesInTx, so a bead
// re-deferred or claimed between the snapshot and its UPDATE is simply skipped.
//
// The caller owns Dolt versioning (commit iff len(result.Issues) > 0) and must
// treat sweep failure as advisory — a ready listing never fails because the
// wake could not run.
func WakeExpiredDefersInTx(ctx context.Context, tx DBTX) (WakeDefersResult, error) {
var result WakeDefersResult
issues, err := wakeExpiredDefersInTable(ctx, tx, "issues", "events")
if err != nil {
return result, err
}
result.Issues = issues
// Wisps carry the same status/defer_until columns and `bd defer` reaches
// them through the same UpdateIssue routing. The table is tolerated absent
// for pre-wisp databases, like every other wisp probe.
wisps, err := wakeExpiredDefersInTable(ctx, tx, "wisps", "wisp_events")
if err != nil {
if dberrors.IsTableNotExist(err) {
return result, nil
}
return result, err
}
result.Wisps = wisps
return result, nil
}
func wakeExpiredDefersInTable(ctx context.Context, tx DBTX, table, eventsTable string) ([]string, error) {
// Snapshot first so each genuinely-woken row gets its own event. The
// UPDATE below repeats the whole predicate, so a row rescued between the
// SELECT and its UPDATE (re-deferred further out, claimed, closed) matches
// nothing and is skipped rather than clobbered.
//nolint:gosec // G201: table is a hardcoded constant from the caller above.
rows, err := tx.QueryContext(ctx, fmt.Sprintf(`
SELECT id FROM %s
WHERE status = 'deferred' AND defer_until IS NOT NULL
AND defer_until <= UTC_TIMESTAMP()
`, table))
if err != nil {
return nil, fmt.Errorf("wake expired defers: scan %s: %w", table, err)
}
var expired []string
for rows.Next() {
var id string
if err := rows.Scan(&id); err != nil {
_ = rows.Close()
return nil, fmt.Errorf("wake expired defers: scan %s row: %w", table, err)
}
expired = append(expired, id)
}
if err := rows.Err(); err != nil {
_ = rows.Close()
return nil, fmt.Errorf("wake expired defers: iterate %s: %w", table, err)
}
if err := rows.Close(); err != nil {
return nil, fmt.Errorf("wake expired defers: close %s rows: %w", table, err)
}
if len(expired) == 0 {
return nil, nil
}
var woken []string
now := time.Now().UTC()
for _, id := range expired {
// row_lock is rewritten so a concurrent claim/update conflicts at
// commit time instead of cell-merging with this write — the same
// invariant the lease scheme depends on.
//nolint:gosec // G201: table is a hardcoded constant from the caller above.
res, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET status = 'open', defer_until = NULL, updated_at = ?, row_lock = ?
WHERE id = ? AND status = 'deferred' AND defer_until IS NOT NULL
AND defer_until <= UTC_TIMESTAMP()
`, table), now, freshRowLock(), id)
if err != nil {
return woken, fmt.Errorf("wake expired defer %s: %w", id, err)
}
n, err := res.RowsAffected()
if err != nil {
return woken, fmt.Errorf("wake expired defer %s rows affected: %w", id, err)
}
if n == 0 {
continue // rescued concurrently — leave it be
}
if err := RecordFullEventInTable(ctx, tx, eventsTable, id, types.EventStatusChanged,
DeferWakeActor, string(types.StatusDeferred), string(types.StatusOpen)); err != nil {
return woken, fmt.Errorf("record wake event for %s: %w", id, err)
}
woken = append(woken, id)
}
return woken, nil
}

View file

@ -50,6 +50,10 @@ var _ publicops.Reader = (*issueReader)(nil)
// detached rollback, so a caller that hangs up mid-response cannot burn a
// pinned session.
func (r *issueReader) Ready(ctx context.Context, req publicops.ReadyRequest) (publicops.IssuePage, error) {
// Wake expired dated defers before reading, in a write UOW of its own —
// this read's span never commits (see the doc comment above), so the
// sweep cannot live inside it.
WakeExpiredDefersAdvisory(ctx, r.provider)
return RunTxRead(ctx, r.provider, func(ctx context.Context, uw UnitOfWork) (publicops.IssuePage, error) {
filter, err := workapi.BuildReadyFilter(req)
if err != nil {
@ -89,6 +93,12 @@ func (r *issueReader) List(ctx context.Context, req publicops.ListRequest) (publ
if req.MaxRows != 0 {
return publicops.IssuePage{}, &publicops.ErrUnsupported{Op: "Reader.List(MaxRows)", Backend: listBackend}
}
// A --ready listing is the ready front by another door, so it wakes
// expired dated defers the same way Ready does — before the read span,
// which never commits.
if req.ReadyFlag {
WakeExpiredDefersAdvisory(ctx, r.provider)
}
return RunTxRead(ctx, r.provider, func(ctx context.Context, uw UnitOfWork) (publicops.IssuePage, error) {
// The config source comes from the unit of work this call already
// holds, so a caller reaching this method through the role has nothing

View file

@ -44,6 +44,12 @@ func (f readerIssues) SearchIssuesWithCounts(context.Context, string, types.Issu
return domain.SearchCountsPage{Items: f.rows}, nil
}
// The ready arm's defer-wake sweep reaches this before the read; a workspace
// with nothing expired is the steady state the fixture models.
func (readerIssues) WakeExpiredDefers(context.Context) (issues, wisps int, err error) {
return 0, 0, nil
}
// readerConfig is a workspace with no custom vocabulary, which is all
// BuildListFilter needs to run.
type readerConfig struct{ domain.ConfigUseCase }
@ -103,10 +109,14 @@ func TestBothReaderImplementationsAgreeOnTheListEpilogue(t *testing.T) {
t.Run(name, func(t *testing.T) {
req := publicops.ListRequest{ReadyFlag: ready, SortBy: "id", Limit: &limit}
provider := &mockUnitOfWorkProvider{uows: []*mockUnitOfWork{{
uw := &mockUnitOfWork{
issueUseCase: readerIssues{rows: readerRows()},
configUseCase: readerConfig{},
}}}
}
// The ready arm opens two units of work — the defer-wake
// sweep, then the read span — and the provider hands out
// zero-valued mocks once the pool runs dry.
provider := &mockUnitOfWorkProvider{uows: []*mockUnitOfWork{uw, uw}}
overUOW, err := NewIssueReader(provider)
if err != nil {
t.Fatalf("NewIssueReader: %v", err)

View file

@ -52,6 +52,11 @@ func (c *readyClaimer) ClaimNext(ctx context.Context, request publicops.ClaimNex
if err != nil {
return publicops.ClaimNextResult{}, err
}
// Wake expired dated defers before selecting, so a bead whose snooze just
// ended is claimable the moment its date passes rather than after some
// other session lists the front. Advisory, in a UOW of its own: a failed
// sweep must not cost the claim.
WakeExpiredDefersAdvisory(ctx, c.provider)
return RunTxResult(ctx, c.provider, func(ctx context.Context, uw UnitOfWork) (publicops.ClaimNextResult, string, error) {
claimed, err := ClaimNextInUOW(ctx, uw, request.Actor, filter)
if err != nil {

View file

@ -0,0 +1,74 @@
package uow
import (
"fmt"
"os"
"sync"
"context"
"github.com/steveyegge/beads/internal/storage/dberrors"
storageissueops "github.com/steveyegge/beads/internal/storage/issueops"
)
// WakeExpiredDefers runs the lazy defer-wake sweep in its own unit of work,
// committing with a wake message iff any permanent issue woke — the same
// commit-iff-changed contract every RunTxResult writer keeps, so the steady
// state (nothing expired) costs one UPDATE on a transaction that never calls
// DOLT_COMMIT.
//
// It runs in a transaction of its own, not the caller's, because every
// ready-work READ in this stack runs under RunTxRead or a caller-owned UOW
// that rolls back — a sweep inside those spans would be silently discarded.
// Sequencing is what matters: sweep first, then read, and the read sees the
// woken rows.
//
// A WISP-only wake takes a third path: wisp tables are dolt_ignored, so the
// wake-message form (DOLT_COMMIT) would find nothing to commit and the
// transaction would roll back, silently discarding the wisp wakes — every
// subsequent ready read would then redo and re-discard the same writes
// forever. Those wakes persist via uw.Commit(ctx, "") — the ephemeral
// plain-COMMIT form RunTxEphemeral keeps for dolt_ignored state (bd-lrgn1) —
// issued inside the work func; a serialization failure from it surfaces as
// the closure's error and retries against a fresh unit of work, exactly like
// a commit issued by RunTxResult itself.
func WakeExpiredDefers(ctx context.Context, p UnitOfWorkProvider) (int, error) {
return RunTxResult(ctx, p, func(ctx context.Context, uw UnitOfWork) (int, string, error) {
issues, wisps, err := uw.IssueUseCase().WakeExpiredDefers(ctx)
if err != nil {
return 0, "", err
}
if issues > 0 {
return issues, storageissueops.WakeDefersCommitMessage(issues), nil
}
if wisps > 0 {
if err := uw.Commit(ctx, ""); err != nil {
return 0, "", err
}
}
return 0, "", nil
})
}
// advisoryAccessDeniedOnce rate-limits the access-denied advisory to one
// warning per process: a read-only-privileged SQL user hits it on every
// ready-front read, and repeating a configuration fact on each `bd ready`
// is noise, not signal.
var advisoryAccessDeniedOnce sync.Once
// WakeExpiredDefersAdvisory is WakeExpiredDefers under the read paths'
// contract: a ready listing must never fail because the sweep could not run,
// so errors are reduced to a stderr warning (warn-once for access-denied).
func WakeExpiredDefersAdvisory(ctx context.Context, p UnitOfWorkProvider) {
_, err := WakeExpiredDefers(ctx, p)
if err == nil {
return
}
if dberrors.IsAccessDenied(err) {
advisoryAccessDeniedOnce.Do(func() {
fmt.Fprintf(os.Stderr, "warning: defer-wake sweep skipped (SQL user lacks write privileges; expired defers will not auto-wake from this client): %v\n", err)
})
return
}
fmt.Fprintf(os.Stderr, "warning: defer-wake sweep skipped: %v\n", err)
}