beads/issueops/heartbeater.go
Julian Knutsen 47d5db39ff
feat(http): bd heartbeat over bd serve (issues.heartbeat), and close the re-arm orphan-lease race (#7600)
* feat(roles): issueops.Heartbeater role on the dolt, embedded and uow legs

Adds issueops.Heartbeater.Heartbeat(HeartbeatRequest{Actor, IssueID}) ->
HeartbeatResult{IssueID, Holder, HeartbeatAt, LeaseExpiresAt, Rearmed},
the lease refresh behind `bd heartbeat`, as its own role with its own
accessor.

- One body: internal/storage/issueops.ExecuteHeartbeatInTx validates
  (*HeartbeatFieldError for a blank/over-long actor or empty id), refuses
  a wisp, then runs RenewLeaseInTx, which is HeartbeatIssueInTx's body
  reporting the renewal. HeartbeatIssueInTx is now a wrapper, so the legacy
  HeartbeatIssue legs answer the same text and sentinels.
- The refresh is fenced on the holder AND on the live claim: after the
  holder-fenced UPDATE, a read in the same transaction requires the issue
  to be in_progress under the holder (the `update leases set` prefix and
  the one IF() the Postgres dialect rewrites are unchanged; a Postgres port
  should expect more serialization retries from that read). A refusal deletes the caller's orphaned lease
  row, and the legs commit that refusal.
- A refresh writes only the lease row: no row_lock, version, updated_at,
  event, journal entry, Dolt commit or hook. A re-arm (a live hand-doled
  claim with no lease row the caller holds) is recorded as a mutation:
  row_lock reminted, updated_at stamped, a lease_rearmed event, a journal
  entry, a version, a Dolt commit (LeaseRearmVersionCommit) and on_update.
  The remint makes a re-arm collide with a racing release or close instead
  of leaving an orphaned lease on an open or closed issue (a pre-existing
  race on every Dolt route). Rearmed is true only when a row was created:
  a same-second refresh (0 changed rows on embedded Dolt) or a holder
  spelled differently refreshes the existing row in place and keeps its
  granted_at/granted_node. Reported times are rounded to whole seconds,
  the stored values; the binds stay unrounded so a same-second refresh is
  never a 0-row UPDATE on Dolt.
- Typed refusals: an absent id is ErrNotFound; a foreign holder is
  *LeaseConflictError{Holder} wrapping ErrAlreadyClaimed; a wisp
  (Ephemeral) or no live claim is *LeaseConflictError wrapping the new
  ErrLeaseNotHeld, which also matches ErrNotClaimable.
- Legs: DoltStore and EmbeddedDoltStore through the issue-operation
  funnel (DOLT_ADD of the named tables, then DOLT_COMMIT -m, after the SQL
  commit); uow.NewHeartbeater through the new uow.RunTxScoped: a refresh or
  a refusal commits with the plain SQL COMMIT (no working-set scan, no Dolt
  commit, nothing another writer left uncommitted is swept), and a re-arm
  commits through the new ScopedCommitter (DOLT_ADD of exactly its tables,
  DOLT_COMMIT -m, never -Am). The legacy HeartbeatIssue doors commit a
  re-arm the same way and keep a refusal's orphan delete, and the
  proxied-server `bd heartbeat` route runs the role's body with the same
  scoped commit.
- Census: storage.Storage gains Heartbeater(); HookFiringStore wraps it
  (fires on_update for a re-arm only, RoleFiresHooks knows it), telemetry
  wraps it, httpapi.timedProvider, uow.notifyingProvider (records a re-arm)
  and externaldeps.uowProvider build it; the journal and version guards
  list the heartbeat family as entry points; the httpclient unsupported
  shell is regenerated and Heartbeater sits on its unsupported allowlist
  until the wire lands.

Conformance: RunHeartbeater* (18 cases) on dolt, embedded dolt and uow:
refresh post-state with the stored times pinned to the result; no
row_lock/current_revision/updated_at/events/journal/issue_versions/
version-control/hook change; a guarded write with the pre-heartbeat
revision still lands; foreign holder refused against an aged lease;
refused after close/release/reclaim/status move; wisp refused; hand-doled
claim re-armed as a mutation; same-second heartbeat is not a re-arm;
orphaned leases on released, closed and reassigned issues refused and
deleted; a refresh and a refusal against a dirty working set make no
commit and leave the other writer's change uncommitted, and a re-arm
commits only its own tables; absent id; request rules; no request mutation. The http leg is
waived until the wire lands.

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

* feat(httpapi): POST /v0/beads/issues/{id}:heartbeat behind issues.heartbeat

Publishes issueops.Heartbeater on bd serve as heartbeatIssue, the served
lease refresh behind `bd heartbeat`.

- Spec: the operation, HeartbeatIssueRequest {actor} and
  HeartbeatIssueResponse {id, holder, heartbeat_at, lease_expires_at,
  rearmed}; no `revision` (a refresh writes nothing to the row) and no
  expected_version (the fence is the holder and the live claim).
  issues.heartbeat joins the capability vocabulary and lease_not_held
  (409) the Problem.code list; `reason: ephemeral` qualifies it for a
  wisp. apigen and the wire-shape golden are regenerated; the golden diff
  is additive only, so wire_revision stays 2.
- Server: route row on the custom-method dispatcher, handleHeartbeat in
  heartbeat.go (claim's actor rules via bodyActor, unknown member and
  query refusals), Config.Heartbeater as a required role (sourceRoles,
  roleSourceNames, the per-request uow.HeartbeaterSource accessor).
  failHeartbeat maps *LeaseConflictError typed fields: a foreign holder
  is the claim's conflict shape (already_claimed + assignee +
  issue_status); no live claim, a wisp included, is the new
  lease_not_held (+ issue_status, + reason: ephemeral for a wisp), matched
  before the generic arms so ErrLeaseNotHeld's ErrNotClaimable never
  surfaces as not_claimable. Its detail names the one state the refusing
  transaction found (closed, open and not claimed, an ephemeral wisp, ...).
- bd serve wires the role from its peeled store (serveRoleSource gains
  Heartbeater); the serve stub stores, the corpus and e2e harnesses, the
  served harness and the encode oracle bind it.
- Wire client vocabulary: OpHeartbeatIssue/issues.heartbeat and
  MethodHeartbeat are CLASSIFIED (the capability set-equality gate),
  ReasonEphemeral is pinned to the server's, and lease_not_held rebuilds
  *LeaseConflictError{Status, Ephemeral} wrapping ErrLeaseNotHeld in the
  native words (the code-table set-equality gate). No accessor yet.

Tests: heartbeat_test.go (request mapping and projection, edge refusals,
every role refusal with its code, members and state-specific detail, the
code row, the capability). The served-http Heartbeater leg
(served_heartbeater_test.go, 18 cases) runs the contract against a real
bd serve through a test-local dial over the store's own dispatch, and the
http-leg waivers are deleted.

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

* feat(http): bd heartbeat over http through httpclient.Heartbeater

The client leg of the served lease refresh, and `bd heartbeat` on the
role for every route.

- httpclient.Store.Heartbeater (heartbeater.go) dials POST
  /v0/beads/issues/{id}:heartbeat through Store.dispatch, so
  issues.heartbeat is preflighted: an older server is refused BEFORE the
  dial with *wire.CapabilityError naming the token (unwraps to
  *storage.ErrUnsupported{Capability: "issues.heartbeat"}); it never falls
  back to a re-claim or a metadata stamp.
- The role's request rules are restated before the dial
  (validateHeartbeatRequest, pinned to
  storeops.ValidateHeartbeatRequest): blank/over-long actor, empty id, each
  a *HeartbeatFieldError.
- Problem mapping: already_claimed (which the shared table rebuilds as the
  claim's ClaimConflictError) becomes *issueops.LeaseConflictError naming
  the holder and wrapping ErrAlreadyClaimed, in the native words ("issue
  already claimed by <holder>"); lease_not_held already arrives as
  LeaseConflictError (Ephemeral from `reason`); not_found is ErrNotFound;
  invalid_argument on `actor` is the role's field error.
- Idempotent: true, the one write this client marks replayable (a repeat
  only moves the expiry later; a replay after a reclaim fails the fence).
- Legacy Store.HeartbeatIssue rides the role. Both leave the generated
  shell and completeness_test's unsupported allowlist.
- `bd heartbeat` takes Heartbeater() from the resolved store on the direct
  routes (dolt, embedded, http) and from the provider's HeartbeaterSource
  on the proxied route (exact id resolution in a read unit of work, then
  the role); runHeartbeatProxiedServer and heartbeat_proxied_server.go are
  deleted. Success output and exit codes are unchanged; refusal text
  changes per route (see CHANGELOG).

Tests: heartbeater_test.go (stub server: preflight refusal naming the
token with no POST, request/answer projection, each refusal's typed
mapping including the wisp's reason, the 503 replay, pre-dial validation,
validator parity, the legacy door). served_heartbeater_test.go runs the
18-case contract through env.subject.Heartbeater(), with
HookedHeartbeater wired off a HookFiringStore. TestE2E_HeartbeatOverHTTP:
real bd against an in-process serve: holder ok with revision and
updated_at unchanged and a guarded write with the pre-heartbeat revision
landing; a non-holder refused against an aged lease that stays untouched;
closed, wisp and unclaimed refused, each naming its own state; an older
server's handshake refused naming issues.heartbeat with no write. Corpus
shapes gc-heartbeat, -non-holder, -closed, -wisp pending until
reference_server.json advertises the token. CHANGELOG entry for the whole
track, including the orphaned-lease race fix.

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

* build(bazel): auto-sync BUILD files

Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/38875641041
(`make bazel-sync`: gazelle, tools/bazel/go_srcs.py, bazel mod tidy).
Only BUILD.bazel, MODULE.bazel and MODULE.bazel.lock are ever pushed; see
scripts/bazel-autofix-push.sh.

* fix(heartbeat): roll back a no-issue refusal; restate refresh vs re-arm

Review fixes for #7600 (adopt-pr apply-fixes, iterations 1-2).

Legacy HeartbeatIssue doors commit a refusal only when it read the issue.
The dolt and embedded HeartbeatIssue callbacks committed every
LeaseRenewalRefusal, including Found=false (the issue read failed). That
refusal deletes nothing, but it can follow a fast-path UPDATE that
already extended an orphan lease row's expiry, so committing it kept the
extension. issueops.LeaseRenewalRefusalCommits now gates the commit on
Found, the rule the Heartbeater role's HeartbeatRefusalCommits applies.
New tests on both legs pin both arms: a no-issue orphan's expiry is
unchanged, and a released issue's orphan is deleted.

Refresh vs re-arm contract docs. Comments, Long help, the OpenAPI spec
and the generated apigen still said every heartbeat writes only the
lease row, makes no Dolt commit and fires no hook. A re-arm is recorded
as a mutation: it remints the revision, records an event and a version
entry, commits once (LeaseRearmVersionCommit) and fires on_update
through the wrapping hook decorator. Restated in domain, uow, issueops,
storage.go (why RoleFiresHooks answers true, so bd serve takes the
heartbeater off a peeled store), cmd/bd heartbeat and serve, httpapi,
httpclient, the spec (apigen regenerated), and the conformance and
contract-test docs.

Minor review findings:
- The 409 already_claimed and lease_not_held details now end "nothing
  on the issue was written": the refusal may have deleted and committed
  the caller's orphan lease row.
- docs/multi-agent/federation.md and the CHANGELOG entry describe the
  spelling-mismatch heartbeat: the row is refreshed in place and keeps
  granted_at and granted_node; only a re-arm stamps this node. The
  embedded spelling test pins both columns, and the lease.go comments
  say "refreshed in place" instead of "re-arms".
- The refusal's orphan delete judges the holder under actorMatches, as
  the in-place refresh does (iteration 2). It matched holder = ? on the
  actor as sent, so a dead claim's orphan held under another spelling
  of the caller (gastown.mayor, heartbeat as gastown__mayor) survived
  the refusal until TTL. The refused closure now reads the row's holder
  and deletes that stored holder only when actorMatches(holder, actor).
  Both TestHeartbeatIssueCommitsARefusalOnlyWhenItReadTheIssue twins
  gain a cross-spelling arm (row deleted) and a control: another
  identity's row (gastown.dog-3) survives.

Not changed: `bd heartbeat --json` still omits `rearmed`, since adding
it changes a CLI JSON contract (follow-up). The federation.md paragraph
post-dates the v1.2.2 docs pin, so documenting this main-only behaviour
there is a maintainer call under
engdocs/decisions/2026-07-17-docs-release-pin.md section 1.

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

* fix(uow): run the scoped re-arm's Dolt commit after the SQL commit

The proxied-server heartbeat commits a re-arm with doltServerTx.CommitScoped,
which ran DOLT_ADD per table and DOLT_COMMIT('-m') INSIDE the open
transaction, before the SQL COMMIT. DOLT_ADD stages whole tables from the
session's transaction root, so that Dolt commit was built from the re-arm's
start snapshot: an issues row another session changed while the re-arm was
open (a write still only in the working set, as in batch mode or before that
writer's own Dolt commit) was staged at its old value, and HEAD disagreed
with the rows every reader sees. This is the LatentLabsSpace/NEXUS#92
ordering the DoltStore funnel (runIssueOperationTxWithMessage) already
avoids, and the review's major finding on this PR.

CommitScoped now commits the SQL transaction first, then stages exactly the
named tables (plus the versioned-history tables) and makes the Dolt commit on
the same pinned connection, the uow twin of doltAddAndCommitPostTx:

- a serialization failure of the SQL COMMIT is still returned, so
  RunTxScoped replays the unit of work;
- the Dolt commit runs detached on its own budget and replays only conflicts
  that leave nothing behind: serialization failures and Dolt's 1105
  "@autocommit transaction rolled back" (new isDoltAutocommitRollbackError,
  mirroring the DoltStore classifier of the same name);
- nothing staged, or "nothing to commit", is not an error: a concurrent
  writer's Dolt commit already took the row. A "nothing to commit" past the
  staged check is logged, as the funnel logs it, so the missing audit line
  is explicable;
- any other failure is logged, never returned. The data is committed, and
  returning it would make RunTxScoped replay a committed re-arm, which would
  then report a refresh. The session is poisoned rather than pooled, since
  its state is unknown. uow records no metrics, so that log line is the
  drop's only signal; bd.db.post_tx_commit_dropped counts only the funnel's.

Statements go through schema.DrainCall, retiring the local drainCall fork
(review nit).

Tests: five sqlmock tests pin the order (SQL COMMIT before any DOLT_ADD),
the swallow-and-poison path, the 1105 retry, the returned serialization
failure and the empty-commit tolerance; each fails against the previous
CommitScoped. TestIsDoltAutocommitRollbackError carries the DoltStore
classifier's table over to the uow copy, plus the prefix boundary; dropping
the prefix branch, the prefix's period, the 1105 check or the type check
each fails a case. TestHeartbeaterRearmKeepsAConcurrentWrite is the
real-Dolt regression: a change to another issues row made while the
re-arm's transaction is open must be at HEAD after the re-arm's Dolt
commit. Its working-set-only writer fails on the old ordering (dolt
2.1.8); the writer that Dolt-commits its own change passes on both and is
kept as coverage.

Review follow-ups folded in (comments, a file move and a test; the
absorption log line above is the only behaviour change among them):

- the freshRowLock invariant and its row_lock_guard_test.go mirror name the
  re-arm as the one deliberate remint without a lifecycle-field change,
  load-bearing for the release/close collision;
- httpclient: "a write is never retried" (wire/client.go, stall_retry.go)
  and "only a read's answer is yes" (dispatch.go) now allow for the
  Idempotent heartbeat, and httpHeartbeater and issueops.HeartbeatResult
  document that a replayed heartbeat can report Rearmed false after a
  committed re-arm, with the guarded write's revision check as the backstop;
- the proxied route moves back to cmd/bd/heartbeat_proxied_server.go, the
  file family cmd/bd/AGENTS.md prescribes;
- the ScopedCommitter and RunTxScoped docs no longer say every other
  writer's uncommitted change stays out of the commit: a staged table is
  committed whole, so such a change to a named table rides in the re-arm's
  commit, as it does in the funnel, and only other tables keep theirs;
- commitStagedTables says its drop is log-only, the absorption is logged,
  and the uow classifier gets its table test (see Tests).

Not folded in: the base-owned IssueUseCase.Heartbeat /
IssueSQLRepository.HeartbeatIssue door, dead in production since the
proxied route moved to the Heartbeater role. Its one caller is the
notifying hook-parity test (uow/notifying_test.go), and moving that case
onto the Heartbeater means re-deriving its RenewLease hook semantics, so it
is left for a follow-up.

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 (1M context) <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
2026-10-16 22:38:23 +00:00

182 lines
8.7 KiB
Go

package issueops
import (
"context"
"fmt"
"time"
)
// ErrLeaseNotHeld is the refusal a heartbeat answers when the caller holds no
// live claim on the issue: it is open, closed, released, reclaimed, moved off
// in_progress, or a wisp (wisps are never leased).
//
// IT ALSO MATCHES ErrNotClaimable, which is what the raw heartbeat has always
// answered for the same states, so a caller written against that sentinel
// keeps working when it moves onto this role.
var ErrLeaseNotHeld = fmt.Errorf("lease not held: %w", ErrNotClaimable)
// LeaseConflictError reports the state that refused a heartbeat, read inside
// the same transaction that found no lease row for the caller. It wraps the
// refusal rather than replacing it, the way ClaimConflictError does, so the
// sentinel still matches and a front door can classify the conflict from
// typed fields instead of parsing prose.
type LeaseConflictError struct {
// IssueID names the issue the heartbeat was refused on.
IssueID string
// Holder is the foreign assignee that holds the claim. It is empty when
// the refusal is about the status (no live claim) rather than a foreign
// holder.
Holder string
// Status is the status the refusing transaction observed.
Status Status
// Ephemeral is true when the id names a wisp, which is never leased.
// Status is then the wisp's own status, which may well be in_progress.
Ephemeral bool
// Err is the wrapped refusal. It matches ErrAlreadyClaimed (a foreign
// holder) or ErrLeaseNotHeld (no live claim by the caller).
Err error
}
func (e *LeaseConflictError) Error() string { return e.Err.Error() }
// Unwrap makes LeaseConflictError match the refusal it carries.
func (e *LeaseConflictError) Unwrap() error { return e.Err }
// The HeartbeatRequest fields a HeartbeatFieldError can name.
const (
HeartbeatFieldActor = "actor"
HeartbeatFieldIssueID = "issue_id"
)
// HeartbeatFieldError reports a HeartbeatRequest refusal and the one field it
// is about, so a front door can name that field without parsing the message.
// It wraps ErrValidation.
type HeartbeatFieldError struct {
// Field is one of the HeartbeatField* constants.
Field string
// Detail is the sentence the error reads as.
Detail string
}
func (e *HeartbeatFieldError) Error() string { return e.Detail }
// Unwrap makes HeartbeatFieldError match ErrValidation.
func (e *HeartbeatFieldError) Unwrap() error { return ErrValidation }
// HeartbeatRequest refreshes the lease on one issue the actor holds — the
// shape behind `bd heartbeat`.
//
// Implementations never mutate caller-owned request values.
type HeartbeatRequest struct {
// Actor is the lease holder refreshing its lease, and the fence's
// subject: only the current holder may heartbeat. It is REQUIRED — a
// blank Actor is ErrValidation — and so is one longer than
// types.MaxFieldLen characters, which no lease row can hold.
//
// THE ROLE DOES NOT TRIM OR CASE-FOLD IT, Releaser.Actor's rule: the
// value is compared with the lease row's holder as sent. A front door may
// normalize before it calls the role: bd serve trims the body's actor by
// the claim's rule (so a served claim and a served heartbeat agree on the
// spelling), and the CLI passes its resolved actor through. A holder
// spelled differently across layers (separator-insensitive, see
// ReleaseRequest.ExpectedAssignee) still heartbeats: it misses the fast
// path, and the slow path refreshes the lease row in place under this
// spelling.
Actor string
// IssueID is the exact canonical id, on either plane, and must not be
// empty. There is no fuzzy or prefix resolution: that is a front-door
// convenience, for the reason GetRequest.ID gives.
IssueID string
}
// HeartbeatResult reports one refreshed lease.
type HeartbeatResult struct {
// IssueID is the issue whose lease was refreshed.
IssueID string
// Holder is the lease holder after the refresh: the request's Actor, in
// the request's spelling.
Holder string
// HeartbeatAt is the server clock, in UTC and rounded to whole seconds
// as the lease row's column rounds it: the stored value.
HeartbeatAt time.Time
// LeaseExpiresAt is HeartbeatAt plus the store's lease TTL: the deadline
// the next heartbeat must beat before a reclaim may revert the claim.
LeaseExpiresAt time.Time
// Rearmed is true only when the heartbeat CREATED the caller's lease row:
// the caller held a live claim but no lease row the caller holds existed
// (a claim hand-doled through a generic update), so the heartbeat granted
// a fresh one instead of refreshing it. A re-arm is recorded as a
// mutation and remints the issue's revision token (see Heartbeater);
// re-read before a guarded write. A refresh of the caller's own row
// is never a re-arm, including one that changed no value (two heartbeats
// in one second) and one under a differently spelled holder.
//
// false does not prove that nothing reminted the token: a transport that
// resends a heartbeat whose answer was lost (the HTTP client does) reports
// the resend's answer, a refresh of the lease row a committed re-arm
// granted. A guarded write composed on the old revision then fails its
// revision check once and re-reads.
Rearmed bool
}
// Heartbeater refreshes a held lease — the capability behind `bd heartbeat` —
// and, like every other capability here, a role with its own accessor.
//
// IT IS A DIFFERENT QUESTION FROM Claimer. A claim takes ownership and is
// idempotent for the holder WITHOUT extending the lease (a re-claim returns
// before the lease is touched); a heartbeat proves the holder is alive and
// does nothing else. Folding one into the other would make every keepalive a
// claim attempt, with a claim's refusals and a claim's history.
//
// A REFRESH WRITES ONLY THE LEASE ROW. A heartbeat touches the ephemeral
// leases table and nothing else: it does not remint row_lock (so the holder's
// own revision token survives it and its guarded writes keep working), it
// records no version (current_revision and issue_versions stay put), it does
// not stamp updated_at, it records no event and no events-journal entry, it
// makes no version-control commit, and it fires no hook. It is the hottest
// write in a fleet, and every one of those would make it expensive or noisy.
//
// A RE-ARM IS RECORDED AS A MUTATION; A REFRESH IS NOT. A re-arm (Rearmed:
// the caller held a live claim with no lease row, a claim hand-doled through
// a generic update) is recorded the way every bead mutator records a write:
// it remints row_lock, stamps updated_at, records a lease_rearmed event, an
// events-journal entry and a version, makes a version-control commit, and
// fires on_update. The remint is what makes the grant collide with a release
// or close racing it, instead of committing beside it and leaving a lease on
// an issue that is no longer claimed. Re-arms are rare (a hand-doled claim's
// first heartbeat), so the cost lands once per such claim.
//
// THE LIVE-CLAIM FENCE IS AN INVARIANT AND A PREDICATE. Every path that ends
// or transfers a claim deletes the lease row, and a re-arm racing such a path
// collides with it on row_lock, so a lease row exists only while its claim is
// live. The refresh also matches the lease row by holder AND requires, in the
// same transaction, that the issue is in_progress with that holder as assignee,
// so a lease row orphaned any other way fails the refresh, and the refusal
// deletes it. A refresh that lands is a refresh of a live claim.
//
// EVERY LEG RUNS ONE BODY: dolt, embedded dolt and the unit-of-work provider
// wrap internal/storage/issueops.ExecuteHeartbeatInTx.
//
// Deterministic request-validation failures match ErrValidation. Result
// values are unspecified when error is non-nil. Every refusal below leaves
// persistent state unchanged, with one exception: a *LeaseConflictError
// refusal deletes the caller's own lease row if one survives on an issue the
// caller no longer holds a live claim on (an orphan; never a live holder's
// lease).
type Heartbeater interface {
// Heartbeat refreshes the lease on request.IssueID held by request.Actor.
//
// REFUSALS:
//
// - a blank Actor, one longer than types.MaxFieldLen characters, or an
// empty IssueID: a *HeartbeatFieldError (ErrValidation), before
// anything is read;
// - an IssueID that names no row on either plane: ErrNotFound;
// - an issue another actor holds: a *LeaseConflictError naming the
// Holder, wrapping ErrAlreadyClaimed;
// - a wisp, or an issue the actor holds no live claim on (open, closed,
// released, reclaimed, or any status but in_progress): a
// *LeaseConflictError wrapping ErrLeaseNotHeld, which also matches
// ErrNotClaimable; Ephemeral is set for a wisp.
Heartbeat(ctx context.Context, request HeartbeatRequest) (HeartbeatResult, error)
}