beads/internal/telemetry
Julian Knutsen 873e3040bf
feat(storage): keyset reads — comments page, issue-list cursor, IsBlocked filter (#4922)
* feat(comments): keyset-paged comments read (GetIssueCommentsPage)

The comments read surface was whole-thread only: GetIssueComments materializes
every comment, so a consumer that wants a page of a long thread must load it
all and page in memory (and cap it, serving long threads incomplete). Add a
keyset-paged read with a stable order and an index-backed resume predicate.

- Storage.GetIssueCommentsPage(ctx, issueID, after CommentPageCursor, limit):
  (created_at ASC, id ASC) order; resume via the sargable predicate
  created_at >= ? AND ((created_at > ?) OR (id > ?)); limit defaults to 100 and
  caps at 500 (documented, with the len(page)<limit idiom hazard called out —
  terminate on an empty page). Cursor comes from a previously read row; the
  forward-only-walk semantics for backdated inserts are documented. Wisp-routed
  like the whole-thread read. Page-walk equals the full read exactly, including
  same-second id tie-breaks (comment ids are lowercase UUIDv7, so the CHAR(36)
  collation cannot reorder them).
- Migration 0056 adds idx_comments_issue_created_id (issue_id, created_at, id)
  on comments and — table-guarded, since wisp tables are clone-local and main
  migrations run before the ignored chain materializes them (the 0035/0037/0053
  precedent, with a matching no-op pin test) — on wisp_comments. Fresh clones
  get the wisp index from the canonical clone-local schema (ignored/0001), the
  same two-path design earlier wisp indexes use. An EXPLAIN guard pins the
  composite index by its column-list signature, single-sourced from the exported
  production query.
- AddIssueCommentInTx now truncates the returned CreatedAt to seconds so the
  returned comment matches what the DATETIME(0) column stored and is usable as
  a page cursor (the stored value is unchanged).
- Implemented on DoltStore and EmbeddedDoltStore; InstrumentedStorage wraps it;
  beads re-exports the cursor type. Tests: page-walk==full-read (same-second
  groups), tie-break, first/past-end/empty/default-limit, wisp routing, the
  migration no-op pin, and the EXPLAIN guard — on both stores.

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

* feat(storage): (created_at, id) keyset issue-list predicate on IssueFilter

`bd list` and the library's own callers over the public Storage surface need
true keyset paging over issues with second-granularity timestamps, which the
surface lacked: IssueFilter had CreatedBefore + Limit but no (created_at, id)
tuple cursor, so a same-second group larger than one page could not page without
dropping or duplicating its overflow.

Add an additive keyset to types.IssueFilter — AfterCreatedAt *time.Time +
AfterID string — meaning "rows strictly after the (created_at DESC, id ASC)
position (AfterCreatedAt, AfterID)". id is the primary key, so the tie-break is
total. It composes with every existing filter (CreatedBefore keeps working) and
is honored by BOTH SearchIssues and SearchIssuesWithCounts on every backend,
because it is emitted through the shared sqlbuild.BuildIssueFilterClauses path
that every storage backend goes through. Pair it with SortBy="created" for the
matching ORDER BY created_at DESC, id ASC.

The predicate is single-sourced as sqlbuild.KeysetCreatedAtIDPredicate:
(created_at <= ? AND ((created_at < ?) OR (id > ?))). This is the keyset
form the planner can drive through an index seek rather than a scan; a dolt
EXPLAIN guard pins the plan against the exact production constant, a sqlbuild
unit test pins clause/args emission, and same-second-overflow paging
regressions run on both the server and embedded Dolt backends through the
public SearchIssues.

(cherry picked from commit 167e25b3af3002939fe27d4bbfc1598fff21c586)

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

* feat(storage): IssueFilter.IsBlocked filter — index-backed on every backend

`bd list`/`bd ready` and the library's own callers could not filter on the
denormalized is_blocked column server-side: the column and the
idx_issues_is_blocked(is_blocked, status) index already exist, but the
projection column was not a filter — callers had to over-fetch and post-filter
in Go. Make it one.

Purely additive: an optional IssueFilter.IsBlocked *bool (nil = any; no
signature change, no new interface method). Wired into the shared sqlbuild
filter clause as `is_blocked = ?` (bound int 0/1; the column is NOT NULL
DEFAULT 0 so no IS NULL arm), so BOTH SearchIssues(WithCounts) AND
CountIssues/CountIssuesByGroup honor it on every backend (dolt, embeddeddolt)
through the one BuildIssueFilterClauses path.

Tests: clause/arg unit test (true→1, false→0, nil→no clause); multi-backend
conformance — CountIssuesByGroup(IsBlocked=true) returns only blocked beads per
status, false the complement, nil the whole population; and a dolt EXPLAIN
guard that the filter drives the is_blocked index.

(cherry picked from commit 96c0b03024f0df08fcada9f312669f970500eea8)

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

* fix(schema): move the wisp comments keyset index to a new ignored-chain migration

CI's migration-hygiene gate froze ignored/0001 (it exists on main; clones have
recorded its content hash), so the wisp twin of the 0056 comments keyset index
cannot be baked into the canonical wisp schema there. Add it as ignored/0014
instead — guarded exactly like ignored/0006 (table exists AND index absent) —
which is strictly better: the ignored chain runs per clone with its own
cursor, so fresh clones AND already-materialized workspaces both pick the
index up; 0056's guarded half remains for workspaces whose wisp tables
existed when the main chain ran. ignored/0001 reverts to its main content.

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

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Test User <test@test.com>
2026-07-21 22:29:09 -07:00
..
otlp.go feat(otel): opt-in OpenTelemetry instrumentation (#1940) 2026-02-22 15:36:57 -08:00
storage.go feat(storage): keyset reads — comments page, issue-list cursor, IsBlocked filter (#4922) 2026-07-21 22:29:09 -07:00
storage_test.go fix(telemetry): wire WrapStorage decorator into bd storage chain (#3858) 2026-07-06 22:27:32 -07:00
telemetry.go docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00