beads/internal/types
Julian Knutsen 470ec832b5
feat(roles): LeaseReclaimer role, POST issues:reclaim, and bd reclaim on both routes (S9) (#7412)
* feat(roles): LeaseReclaimer role and POST issues:reclaim (S9)

Adds issueops.LeaseReclaimer.Reclaim(ReclaimRequest{Actor, OlderThan,
Filter}) -> ReclaimResult{Reclaimed []ReclaimedLease{ID, PreviousOwner,
Revision}}, the stale-lease sweep behind `bd reclaim`, on every leg:

- dolt, embedded dolt and the unit-of-work provider all run one body,
  internal/storage/issueops.ExecuteReclaimInTx over
  ReclaimExpiredLeasesInTx, and record one version commit per sweep that
  reverted anything through the issue-operation funnel (so a deferred
  version commit on the context is honored);
- each reverted row's fresh row_lock is published as its revision, so a
  former holder's guarded write fails with ErrVersionMismatch;
- an id that is not a stale lease (absent, live, unheld) is left out of
  Reclaimed, never an error; the id scope is capped at 1000
  (*TooManyReclaimIDsError, counted as sent);
- the hook decorator fires on_update once per reverted row (and the
  proxied notifying provider records one update per row); telemetry
  wraps it like every role.

bd serve publishes it as POST /v0/beads/issues:reclaim behind the new
issues.reclaim capability (httpapi.Config.LeaseReclaimer, required like
every role). Spec, apigen and the wire-shape golden are regenerated;
the change is additive and wire_revision is unchanged. The HTTP client
leg dials it (wire vocabulary, capability preflight, local validation
in the role's order).

Conformance: RunLeaseReclaimer* (12 cases: revert post-state, the
revision race, live lease, grace window, id scope with absent/live ids,
empty answer, assignee/label scopes re-homed from reclaim_scope.go,
recovery event attribution, on_update once per row, refusals, the cap
boundary, no request mutation) wired on dolt, embeddeddolt, uow and the
served http leg, and so held by the leg lock. Handler tests cover the
member mapping, the projection, every handler refusal by name and the
role's refusals reaching the wire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(bd): bd reclaim runs the LeaseReclaimer role on both routes (S9)

`bd reclaim` takes issueops.LeaseReclaimer off the decorated store on the
direct route (so a connected HTTP workspace dials issues:reclaim instead
of refusing) and off the proxied provider's own accessor on the proxied
route, replacing the raw ReclaimExpiredLeases calls and
runReclaimProxiedServer. Visible changes: --json entries carry the
reverted row's new `revision`, the workspace's on_update hook fires once
per reverted row, and the version commit is the role's own
("bd: reclaim N expired lease(s)", honoring dolt.auto-commit through the
context the way bd prune does).

Tests: an embedded direct-route CLI test (scoped sweep with a live and an
absent id, revision, one version commit, on_update once) and the proxied
reclaim integration test now asserts the revision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(roles): S9 review LOWs: one validator, field attribution, overflow bound

- The library's ValidateReclaimRequest is the one definition of a valid
  reclaim: it now also refuses a blank assignee/label/label-any/exclude
  entry, and every refusal but the id cap is a *issueops.ReclaimFieldError
  naming its field. The httpapi handler no longer checks blank entries
  itself; failReclaimErr names the member the role's error is about
  (`ids` for the cap) instead of blaming `ids` for every validation. The
  HTTP client's restatement matches, pinned field by field.
- older_than_seconds is refused at >= MaxInt64/1e9: that float rounds to
  2^63 ns, which wrapped negative under the old > check.
- New contract case RunLeaseReclaimerRefusesABlankScopeEntry on all four
  legs; handler tests for field attribution and the overflow boundary.
- CHANGELOG names the 1000-id cap on bd reclaim --id and is rewrapped; the
  client's grace-window precision comment no longer claims exactness.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(roles): S9 review: regenerate the unsupported shell, cgo-tag the embedded contract, one actor spelling

- go generate ./internal/httpclient: the new accessor moves the partial-shell
  trailer to 145 of 200.
- lease_reclaimer_contract_test.go gets //go:build cgo like its siblings, so
  the pure-Go lane compiles.
- The library trims the actor before attributing, matching the handler, so
  " alice " is attributed the same on every route.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(roles): S9 review minors: bound the reclaim actor on every leg, pin any_replica, validate before the uow

Review minors on #7412, each in code this PR adds.

- The reclaim actor lands on every reverted row's recovery event, in a
  VARCHAR(255) column, but ValidateReclaimRequest never bounded it: a
  256-character actor passed validation on the dolt, embedded-dolt and
  unit-of-work legs and failed the sweep with the backend's own
  "Error 1105: string '...' is too large for column 'actor'" on the first
  row it would have reverted (all three legs answer exactly that with the
  bound below removed). The shared validator now holds the trimmed actor to
  types.MaxFieldLen, as claimIssueInTx does, so it is a *ReclaimFieldError
  for `actor` on every leg. The HTTP client restates the rule, and the parity
  test covers both sides of it. bd serve already refused it through the
  claim's name rules. The role's Actor and REFUSALS docs name the bound, and
  the conformance case runs it on all four legs.
- ValidateReclaimRequest's doc no longer says bd serve's handler leaves every
  rule to it: it names the three wire rules the handler adds of its own.
- TestReclaimSendsAnyReplicaOnlyWhenAsked pins the one filter member that
  widens a sweep: the client sends any_replica only when the caller set it.
- The unit-of-work leg validates before opening its unit of work, as the dolt
  and embedded-dolt legs do; TestLeaseReclaimerRefusesBeforeOpeningAUOW pins
  it.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 14:56:32 +00:00
..
BUILD.bazel ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
explain_test.go fix(ready): --explain sorts a ready issue's blocking edges by status instead of calling a pinned dependency resolved (#7124) 2026-10-06 22:46:47 +00:00
gated.go show/list: render a derived GATED decoration when an open gate holds the bead (#6606) 2026-10-08 10:37:51 +00:00
gated_test.go show/list: render a derived GATED decoration when an open gate holds the bead (#6606) 2026-10-08 10:37:51 +00:00
id_generator.go refactor: consolidate ExtractPrefix into types package 2026-03-02 23:17:14 -08:00
id_generator_test.go style: run gofmt across entire codebase (bd-nmk12) 2026-02-07 19:35:20 -08:00
issue_summary_test.go perf(storage): SearchIssueSummaries narrow-projection foundation (be-nu4.3) (#3458) 2026-10-01 01:19:24 -07:00
non_completing_close.go fix(epic): do not treat duplicate/wontfix closes as complete (#5138) 2026-10-01 05:19:33 -07:00
non_completing_close_test.go fix(epic): do not treat duplicate/wontfix closes as complete (#5138) 2026-10-01 05:19:33 -07:00
orphans.go chore: clean up stale SQLite references in comments (bd-nlw2m) 2026-02-18 11:50:52 -08:00
storage_class_test.go feat(storage): one guarded issue-lifecycle surface for the CLI and linked consumers (#5191) 2026-07-31 11:26:38 -07:00
storage_ext.go fix(compact): archive content before destructive compaction; make restore work (#4464) 2026-06-20 14:12:07 -07:00
types.go feat(roles): LeaseReclaimer role, POST issues:reclaim, and bd reclaim on both routes (S9) (#7412) 2026-10-09 14:56:32 +00:00
types_test.go feat(httpclient): write-role conformance on the http leg — ceiling to zero, sweeper extension (S4) (#7251) 2026-10-08 16:28:56 +00:00