beads/issueops/counter.go
Julian Knutsen 601be8a6bf
feat(list): bd list's remaining filters over http behind issues.list.filters (#7647)
* feat(list): bd list's remaining filters over http behind issues.list.filters

Over http every `bd list` filter beyond the created bounds and the title,
id and no-assignee scope refused (time bounds, priority range, text and external-ref
matches, spec, label pattern/regex, exclude-type, no-parent, no-labels,
empty-description, pinned/no-pinned, deferred, overdue, mol/wisp type).
The library entry already applied all of them: issueops.Reader.List via
workapi.BuildListFilter, shared by the CLI and the handler. This adds
only the wire.

- Server: GET /v0/beads/issues decodes 29 new optional parameters
  (listFilterParams, decode only; countIssues' names where it already
  spells the filter) into the existing ListRequest, behind one new
  behavior token, issues.list.filters. mol_type/wisp_type are closed
  enums refused by name (an empty value too). wire_revision stays 2;
  apigen and the wireshape golden are regenerated (additive only).
- Every RFC 3339 bound the listing and count decode is normalized to UTC,
  so an offset-bearing bound selects what its Z twin does on a zone-less
  timestamp column.
- workapi.BuildListFilter refuses PinnedFlag with NoPinnedFlag
  (ErrValidation, the CLI's own sentence) instead of letting PinnedFlag
  win; over http that is a 400 on no_pinned.
- Client: the encoder sends the members (encode.ListFiltersMembers, one
  list read by the encoder, the pre-dial gate and a spec-parity test).
  Against a server not advertising the token, httpReader.List refuses
  before dialing with ErrUnsupported naming issues.list.filters. The 29
  E-ListRequest ledger refusal rows retire; the ledger doc is updated;
  skew flag mappings added.
- Tests: handler decode/parity/enum/UTC/malformed/pinned-pair tests;
  encode member/gate/spec parity and bound encoding; per-member
  ride-behind-token and pre-dial skew refusal; two new Reader contract
  cases on every leg (dolt, embedded, uow, served): the eight time
  bounds at exact boundaries (strict, whole-second truncation, NULL never
  matches, +02:00 equals UTC) and one in/out row per remaining family;
  three served Reader cases unparked; TestE2E_ListFilterParityOverHTTP
  (served == embedded, masked server refuses naming the token, no dial);
  five corpus shapes marked pending until the reference server profile
  advertises the token.

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

* feat(list): exclude_status on listIssues, the 30th issues.list.filters member

issueops.ListRequest gains ExcludeStatus: statuses to leave out of a
listing, appended to the default exclusions (never re-admitting what they
hide), comma-separated or repeated, and validated against the workspace's
statuses by the same rule CountRequest.ExcludeStatus uses (an unknown name
is ErrValidation). The rule moves into one shared function,
workapi.ParseExcludeStatus, called by both builders. With AllFlag it reads
the active set without enumerating every status, so an http-backed caller
can list O(active) rows instead of the whole history.

- Server: listIssues decodes a repeatable `exclude_status` under the same
  issues.list.filters token (no new token); an unknown name is a 400 on
  exclude_status. apigen and the wireshape golden are regenerated
  (additive).
- Client: the encoder sends it and it joins encode.ListFiltersMembers, so
  the pre-dial gate asks for the token.
- It is refused together with ReadyFlag, like the other members the ready
  query cannot carry.
- No `bd list --exclude-status` flag yet (it would need the CLI docs
  regenerated); the member is reachable through the library and the wire.

Tests: builder unit test (append, AllFlag, comma split, unknown name);
handler decode and 400; encoder, round-trip and gate; Reader contract
cases on every leg (active set under AllFlag, repeated and comma values,
adds to the defaults, narrows an explicit Status, unknown name refused).

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

* fix(list): label_regex compile errors are 400s; review polish for list filters

- An invalid `label_regex` on GET /v0/beads/issues, /v0/beads/ready and
  /v0/beads/ready:count is now `400 invalid_argument` (`invalid_value` on
  `label_regex`) instead of `500 internal`. The database still compiles
  the pattern in its own dialect; a request that sent a regex and earned
  the engine's "regular expression is invalid" refusal is attributed to
  the parameter (failRegexReadErr). The same text on a request with no
  regex stays a server fault.
- mol_type and wisp_type refuse each other's vocabulary (tests pin
  `mol_type=heartbeat` and `wisp_type=swarm`), so the call-site
  allowlist, not just the spec enum, is covered.
- exclude_status with a workspace custom status: leg tests on the
  embedded store and over the served wire (accepted and applied; a name in
  no vocabulary refused). ReaderFixture cannot configure custom statuses,
  so these sit beside the count's twin rather than in the contract.
- The search e2e gains a positive arm: --desc-contains returns exactly the
  row whose description carries the token.
- Docs: `all` plus `exclude_status` keeps every status not named (pinned,
  hooked and custom done/frozen included unless named), not "the active
  set"; label_regex documents its 400. A corpus source line is made
  neutral; a test message says 30.

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

* fix(list): compose issues.list.filters with the --title-contains fold

#7631, now on main, folds `bd list --title-contains` onto listIssues
`title` and refuses the TitleContains left over from a --title and
--title-contains pair that differs, because the listing then had one
title parameter. This branch publishes `title_contains` behind
issues.list.filters, so that leftover now rides it beside `title` and
the server applies both. Neither half is dropped, and against a server
without the token the pre-dial gate refuses, naming issues.list.filters.

- encode.FoldTitleContains still runs first; its doc now says where a
  differing pair goes.
- Tests: the fold table expects `title` plus `title_contains` for a
  differing pair, including the ſ/s pair strings.EqualFold would match;
  the differing-pair refusal names issues.list.filters; the
  list_filters_test sweep pairs its TitleContains probe with a differing
  TitleSearch, since a lone one asks only for issues.list.title; the e2e
  differing-pair refusal becomes a listFilterShapes row that answers
  exactly child-a over http and embedded, and refuses before dialing
  without the token.
- The gc-polecat-closed-after corpus shape's pending reason also names
  issues.list.title. The CHANGELOG --title-contains entry no longer
  lists the differing pair and --closed-after as refused.

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

* build(bazel): auto-sync BUILD files

Applied from the bazel-sync-patch artifact of https://github.com/gastownhall/beads/actions/runs/39013611268
(`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(list): serve --priority-max in search parity, refuse the parent pair

The proxied tier's search parity table still expected a remote
`bd search --priority-max 1` to refuse, because listIssues could not
carry it. This branch serves priority_max behind issues.list.filters,
so the remote route answered and the dolt-race shard went red in
TestProxiedServerSearchRoutesAgree. The row now expects the answer on
every route. It was the last wireCan=false row; the branch stays, with
a comment, for the next flag listIssues cannot carry.

- ParentID with NoParent: a served listing now carries no_parent beside
  parent, and ANDing the two answered only the edge-less rows under the
  parent's dotted id. BuildListFilter refuses the pair with
  ErrValidation, in the sentence bd list and BuildCountFilter already
  use, so issueops.Reader.List refuses it on every backend and the
  listing answers 400 on no_parent. Pinned by a builder test, a reader
  conformance case (dolt, embedded, uow, served http) and two httpapi
  tests.
- POST /v0/beads/issues:claimNext shares the ready listing's
  label_regex but answered a pattern the database cannot compile with
  500. It now gives the listing's 400 invalid_value on label_regex,
  through the helper the listing's mapping is split into.
- The descendant walk's ledger rows said listIssues publishes no
  parameter for members it now serves behind issues.list.filters. They
  now say the walk does not send them yet, and that --flat or --json
  asks listIssues directly. The ExcludeStatus, Pinned and ExcludeTypes
  rows, the parentwalk.go header, the walk table's doc and two walk test
  comments are corrected the same way, and the ledger doc is
  regenerated. parentWalkRefusals notes that a member moved off the list
  must check issues.list.filters itself, because the walk dials past
  the listing's pre-dial gate.
- Spec: the listing's no_parent documents the pair's 400, the count's
  exclude_status no longer says it has no listing counterpart, and
  claimNext's label_regex documents its 400. types.gen.go is
  regenerated. Comment-only: countFilters, and readyScopeFields'
  ExcludeStatus entry.
- CHANGELOG and README say the default `bd list --parent` tree view
  does not carry the new filters yet; the label_regex entry names
  claimNext, and a Changed entry records the parent-pair refusal.

Second review pass: docs and comments only, no behavior change.

- The prose copies of the issues.list.filters member set now match
  ListFiltersMembers: CapIssuesListFilters and wire.CapListFilters name
  the status exclusion, and the spec's capabilities text names
  label-regex.
- Every time bound on the listing and the count goes through
  q.timestamp, which normalizes it to UTC, and sqlbuild compares it
  strictly at whole-second precision. listIssues' created_before and
  created_after, and countIssues' created, updated and closed bounds,
  now say so in the words the new listing bounds use. The count's
  updated bounds also say what they filter, and its closed bounds say
  that a NULL closed_at never matches. types.gen.go is regenerated.
- README and CHANGELOG: `--flat` or `--json` applies the filters to the
  parent's direct children, not its whole subtree.
- The 29 listRefusal rows this branch serves stay deleted rather than
  kept as retired rows, as #7550 deleted its TitleSearch, IDFilter and
  NoAssignee rows when it served them. The CHANGELOG now says the rows
  are removed, not retired.

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: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-17 11:21:18 +00:00

333 lines
17 KiB
Go

package issueops
import (
"context"
"time"
)
// CountGroup names a bucketing dimension for a grouped count. The set is
// closed: a value outside it is ErrValidation rather than an empty answer,
// because a caller that misspelled a dimension and got zero buckets back has
// no way to tell that from a store with nothing in it.
type CountGroup string
const (
CountGroupStatus CountGroup = "status"
CountGroupPriority CountGroup = "priority"
CountGroupType CountGroup = "type"
CountGroupAssignee CountGroup = "assignee"
CountGroupLabel CountGroup = "label"
)
// CountRequest describes one issue-count query: the predicate, and nothing
// about a page.
//
// It is a HIGH-LEVEL request in the sense ReadyRequest and ListRequest are —
// label normalization, id splitting and the wisp-tier policy all happen inside
// — but it is NOT a ListRequest with the paging fields removed, and the
// difference is the whole reason this is a separate type. A default `bd list`
// hides closed, pinned, template and gate rows; a default `bd count` hides
// none of them and answers for every durable row that matches. Sharing
// ListRequest would have made the two questions look interchangeable at the
// call site while their answers differed by every one of those exclusions.
//
// THERE IS NO Limit AND NO Offset, deliberately. A count is a cardinality:
// bounding the scan would answer "how many of the first N" and there is no
// front door that wants that. The storage seam ignores both fields on the
// count path, so accepting them here would be accepting two knobs that do
// nothing.
//
// THERE IS NO FREE-TEXT QUERY either. The count seam takes one — the same
// full-text argument search does — and both front doors have always passed the
// empty string. A field no caller sets is a field whose behavior nothing
// checks, so it is left off rather than published untested; TitleSearch and
// the three *Contains fields are the substring matches that ARE reachable.
type CountRequest struct {
// Status restricts to one stored status. Empty and the literal "all" both
// mean every status, which is what makes a bare count answer for closed
// rows as well as open ones.
//
// It is NOT validated against the workspace vocabulary and NOT a
// comma-separated OR set: an unrecognized name matches nothing and returns
// zero rather than failing, exactly as ReadyRequest.IssueType does. That is
// the shipped behavior of both front doors and it is stated here rather
// than quietly tightened, because a scripted caller that counts a status
// its workspace has since dropped currently reads 0 and would start reading
// an error.
//
// "all" is this field's one well-defined non-literal spelling, and it is
// NOT ErrValidation: it is equivalent to leaving Status empty, and
// BuildListFilter treats its own "all" selector identically (the no-filter
// spelling), so `bd count --status all <predicate>` and `bd list --status
// all <predicate> --all` already agree on cardinality for the shared part
// of the predicate. Rejecting it here would break that count/list parity
// (the whole point of this role, GH#4387) for every caller already
// spelling it, and there is no caller-visible ambiguity it would resolve:
// "no status" is a filter that excludes every row, which "all" has never
// meant on either front door.
Status string
// IssueType restricts the type, with the same match-nothing-rather-than-fail
// treatment Status gets and no alias expansion at all.
//
// It has a SECOND effect under IncludeInfra: an infra type routes the count
// to the ephemeral tier. See that field.
IssueType string
// Assignee restricts to one actor's rows; NoAssignee restricts to rows with
// none. Setting both is not refused — they are handed to the filter as
// written and answer with the empty intersection.
Assignee string
// ParentID restricts to one issue's children, spelled as
// ListRequest.ParentID spells it: a parent-child dependency edge, OR (for
// an issue with no such edge) a dotted-id prefix match. NoParent restricts
// to rows with no parent-child dependency edge. It does not consult the
// dotted-id convention, so an edge-less dotted-id child (X.1) still counts
// as top-level — it is counted by BOTH ParentID X and NoParent, as it is
// listed by both `bd list --parent X --flat` and `bd list --no-parent`.
//
// Setting both IS refused, as ErrValidation, UNLIKE Assignee/NoAssignee
// above: `bd list`'s CLI already refuses `--parent` with `--no-parent`
// (cmd/bd/list_input.go) with this same wording, and a caller reaching
// this role directly — over HTTP, or through a future client that skips
// the primary CLI's flag parser — gets the identical refusal rather than
// a silent empty-intersection answer the primary CLI would never have let
// it ask for.
ParentID string
NoParent bool
// Priority is an exact priority; PriorityMin and PriorityMax bound a range
// inclusively. All three are pointers because 0 is a real priority, for the
// reason ReadyRequest.Priority gives.
Priority *int
PriorityMin *int
PriorityMax *int
// Labels must ALL be present; LabelsAny requires at least one. Both are
// raw: entries are trimmed and de-duplicated INSIDE, and a slice whose
// entries are all blank is the same as an unset one.
Labels []string
LabelsAny []string
// TitleSearch is a case-insensitive substring match on the title.
TitleSearch string
// IDFilter is a comma-separated id set. Splitting, trimming and
// de-duplication happen inside, so a caller passes the string it was given
// rather than a slice it had to prepare.
IDFilter string
// ExcludeTypes names types to exclude, spelled as ListRequest.ExcludeTypes
// spells it: entries may be comma-separated, splitting and normalization
// happen inside, and an entry is NOT validated against the workspace
// vocabulary — an unrecognized type excludes nothing rather than failing.
// It composes with IncludeInfra's own "gate" exclusion rather than
// replacing it: both contribute to the same exclusion set.
ExcludeTypes []string
// ExcludeStatus names statuses to exclude (behavior token
// `issues.count.scope`; ListRequest.ExcludeStatus is its listing twin,
// validated by the same rule): entries may be comma-separated, and — UNLIKE
// Status and ExcludeTypes above — each name IS validated against the
// workspace vocabulary (built-in statuses plus the workspace's own custom
// ones). An unrecognized name is ErrValidation rather than excluding
// nothing: a caller building an exclusion list by hand gets a loud failure
// on a typo instead of a silently wider, overcounted answer.
ExcludeStatus []string
// TitleContains, DescContains and NotesContains are substring matches on
// the three long fields, spelled as ListRequest spells them so the two
// requests cannot drift apart in naming while meaning the same thing.
TitleContains string
DescContains string
NotesContains string
// MetadataFields requires equality for every top-level key/value pair and
// HasMetadataKey is a top-level key-presence filter, spelled as
// ListRequest and ReadyRequest spell them. Keys are validated inside.
MetadataFields map[string]string
HasMetadataKey string
CreatedAfter *time.Time
CreatedBefore *time.Time
UpdatedAfter *time.Time
UpdatedBefore *time.Time
ClosedAfter *time.Time
ClosedBefore *time.Time
// EmptyDesc, NoAssignee and NoLabels restrict to rows missing each of those.
EmptyDesc bool
NoAssignee bool
NoLabels bool
// IncludeInfra switches the count from the durable plane to the cardinality
// of `bd list --include-infra --all`, which is FOUR changes at once and not
// one (GH#4387):
//
// - the ephemeral wisps tier is merged in, picking up both wisps and the
// no_history beads that are durable work stored in that tier;
// - template molecules are excluded, which a default count includes;
// - gate beads are excluded, unless IssueType asks for gates by name;
// - an IssueType the workspace calls infra routes the count to the
// ephemeral tier instead of the durable one — unless IncludeEphemeral
// is also set, which lifts that routing, as it does for a listing.
//
// The infra vocabulary is the WORKSPACE's, read from configuration inside
// the implementation. A caller does not supply it and cannot: that is the
// config load this role exists to keep off both front doors.
//
// Unset — and with IncludeEphemeral also unset — the count is durable-plane
// only and applies none of those four: the historical `bd count` answer,
// kept exactly so a scripted caller reads the same number it read yesterday.
IncludeInfra bool
// IncludeEphemeral admits the EPHEMERAL PLANE — the wisps TABLE — and
// admits nothing else. It is the plane knob on its own: exactly the first
// of IncludeInfra's four changes, with none of the other three.
//
// It exists because there was no way to ask for that one thing. The write
// path routes on STORAGE CLASS, not type (dolt's useWispsTable is
// `Ephemeral || NoHistory || WispType != "" || IsInfraType`), so a
// no_history task lives in the wisps table while remaining ordinary durable
// work. Counting it needed IncludeInfra, which ALSO drops template rows of
// the named type — a silent undercount traded for a silent undercount.
//
// Same meaning as ListRequest.IncludeEphemeral (see issueops/reader.go):
// both admit the same PLANE under the same filters. It does NOT promise the
// two answers are equal — a count and a listing already differ on TEMPLATES
// without this flag, and still do with it. A count includes template rows
// unless IncludeInfra excludes them; a listing excludes them unless
// IncludeTemplates admits them. That predates this field and is unchanged by
// it; only IncludeInfra sets out to reconcile cardinality, and it pays for
// that with three changes beyond the plane.
//
// Beside IncludeInfra it does one thing more, the same thing it does to a
// listing: it lifts the fourth change's routing of an infra IssueType, so
// the durable rows of that type (a promoted wisp, a retyped issue) are
// counted along with its wisps rather than instead of them.
//
// Unset — and with IncludeInfra also unset — the count is durable-plane
// only: the historical answer, unchanged.
IncludeEphemeral bool
}
// CountResult is the cardinality of the matching set.
type CountResult struct {
// Total is the number of matching rows. It is an int64 because the storage
// seam counts in one, not because a workspace is expected to hold four
// billion beads.
Total int64
}
// CountByGroupRequest describes one bucketed count.
type CountByGroupRequest struct {
// Filter is the same predicate a scalar count takes, so the two questions
// cannot be asked of different sets. It is embedded by NAME rather than
// anonymously: a grouped count is a scalar count plus a dimension, and
// spelling the dimension beside the whole filter says that, where promoted
// fields would have made GroupBy look like one more predicate.
Filter CountRequest
// GroupBy is the bucketing dimension and must be one of the five
// CountGroup constants. An empty or unknown value is ErrValidation, not a
// scalar count in disguise: a caller that wanted a number calls Count.
GroupBy CountGroup
}
// CountByGroupResult is one bucketed count.
type CountByGroupResult struct {
// Groups maps each bucket's DISPLAY key to its cardinality. The keys are
// normalized, and the normalization is part of this contract because both
// front doors print them unmodified:
//
// - a priority bucket is "P" followed by the number, so priority 1 is
// "P1";
// - the assignee bucket for unassigned rows is "(unassigned)", never the
// empty string, which would be indistinguishable from a store whose
// assignee column holds one;
// - the label bucket for rows carrying no label at all is "(no labels)",
// and it is ABSENT rather than zero when every matching row has one;
// - status and type buckets are the stored value verbatim.
//
// A dimension with no matching rows yields an empty map, never nil.
Groups map[string]int
// Total is the cardinality of the whole matching set — the SAME number a
// scalar Count of Filter returns, and NOT the sum of Groups.
//
// The two differ for exactly one dimension, and it is the reason this field
// exists rather than being left to the caller to add up: label buckets
// OVERLAP. An issue carrying three labels is one row in Total and one row
// in each of three buckets, so a caller that summed them would report a
// workspace three times its size. Every front door that prints a grouped
// count prints a total above it, and deriving that total is a decision this
// role makes once instead of each surface making it again.
//
// It is NOT promised to be one snapshot with Groups. The store-backed
// implementation runs the scalar and the grouped query separately, so a
// concurrent write between them can leave Total disagreeing with the
// buckets by that write. Nothing here is transactional across the two, and
// a caller reconciling them under load should not expect it to be.
Total int64
}
// Counter describes counting issues: the operation `bd count` performs, and —
// like Lifecycle, Reader, ReadyClaimer, BatchCloser, DependencyEditor,
// Commenter and Relations — a role with its own accessor. A new capability
// gets a new role interface and its own accessor; never append a method here.
//
// IT IS ITS OWN ROLE RATHER THAN A COUNTED VARIANT OF Reader because it
// answers a different question. Reader answers with PAGES OF ISSUES: its
// requests carry a limit, an offset, a keyset position, a sort and a has-more
// verdict, and every one of those describes which rows come back and in what
// order. A count has no rows and therefore no order, no page and no cursor —
// it is a number about a set. Folding it into Reader would have meant a
// request type carrying paging fields that a count must ignore, which is the
// shape that makes a caller believe `--limit 10` bounded the answer.
//
// BOTH METHODS BELONG TO THE ONE ROLE, and that is not the rule bending. The
// governing rule forbids APPENDING to an existing role, not a role being born
// with the two shapes of one question: a scalar count and a bucketed count ask
// the same predicate of the same set and differ only in whether the answer is
// one number or a number per bucket. They also cannot be separated in
// practice — a grouped answer carries the scalar Total, because label buckets
// overlap and the sum is wrong (see CountByGroupResult.Total) — so splitting
// them would put one role's promise inside another role's result.
//
// WHAT IS NOT HERE. `bd status` and its `bd stats` alias look like counts and
// are not: their numbers are dependency-aware (ready work, blocked work,
// staleness) and are not expressible as a predicate over one table, so they
// get a role of their own rather than a sixth CountGroup. The count of READY
// work is likewise a different question — the ready predicate is not a filter
// this request can describe — and is its own role for the same reason.
//
// Implementations never mutate caller-owned request values, snapshot the
// request at method entry, and apply normalization only to attempt-local
// clones. That promise is load-bearing here and not merely conventional:
// CountRequest carries two slices, and label normalization is the step that
// would otherwise write through them.
//
// Counting is a READ. Nothing here records a history entry, fires a completion
// hook or changes a row, and a refusal changes nothing either. Deterministic
// request-validation failures match ErrValidation; result values are
// unspecified when error is non-nil.
//
// THE PER-ROLE COST of adding a role like this one — the accessor, the two
// decorator wrappers, the unit-of-work source and the three conformance
// wirings — is written down in engdocs/ADDING_AN_ISSUEOPS_ROLE.md. Counter is
// the role that checklist was derived from.
type Counter interface {
// Count returns how many issues match the request. An empty request counts
// every durable row in the workspace, including closed ones: a count
// applies none of the listing's default exclusions.
//
// A predicate that matches nothing is 0 and a nil error. That is the whole
// of the "not found" story for this role — there is no ErrNotFound here,
// because a question about a set has an answer even when the set is empty,
// and a caller polling for work would otherwise have to classify an error
// to read a zero.
Count(ctx context.Context, req CountRequest) (CountResult, error)
// CountByGroup returns the same count bucketed by one dimension, plus the
// scalar Total of the whole matching set.
//
// An unknown GroupBy is ErrValidation. Buckets with no rows are absent
// rather than present at zero: the dimensions are open-ended (any assignee,
// any label, any custom status), so there is no closed set of keys to
// enumerate and a caller reads absence as zero.
CountByGroup(ctx context.Context, req CountByGroupRequest) (CountByGroupResult, error)
}