beads/internal/httpapi
Steve Yegge 01f9166810
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>
2026-08-07 04:34:38 -07:00
..
apigen Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
spec Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
batch_create.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
batch_create_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
blocking.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
blocking_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
claim.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
claim_test.go feat(issueops): put bd purge and bd prune behind the Sweeper role (bd-pn231) 2026-08-05 16:40:26 +00:00
context_test.go feat(serve): bd serve skeleton — lifecycle, mode gate, /healthz, /v0/beads/context (bd-60z) 2026-07-31 10:07:14 +00:00
cursor.go feat(issueops): add the Reader role and wire both front doors through it 2026-07-31 18:37:25 +00:00
cycles.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
cycles_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
doc.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
edges.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
edges_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
handlers.go refactor(context): one snapshot-to-fields projection for both context surfaces 2026-07-31 22:35:09 +00:00
memories.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
memories_test.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
pinning.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
problem.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
problem_test.go feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb) 2026-07-31 08:37:34 +00:00
query.go feat(issueops): add the Reader role and wire both front doors through it 2026-07-31 18:37:25 +00:00
reads.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
reads_test.go fix(defer): auto-wake expired dated defers on ready-front reads and claims (bd-i8qx8) (#5386) 2026-08-07 04:34:38 -07:00
ready_count_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
roles.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
roles_test.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
routes.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
server.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
server_test.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
settings.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
spec_parity_test.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
stats.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
stats_test.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
sweep.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
sweep_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
timed_provider_binding_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
tree.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
tree_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
wire_bijection_test.go chore(facade): reconcile wave 4's four slices and close the programme 2026-08-06 03:36:58 +00:00