* fix(list): expose comment bodies and mark the omission in bd list --json (be-73x)
`bd list --json` reported comment_count and carried no comment text and no sign
that any was missing. The consequence is not a missing field: a content search
over a listing answers with a well-formed, NON-EMPTY result set whose matching
rows are absent, and nothing about that answer invites a second look. An empty
result invites suspicion; eight rows do not.
Two halves, and the second is the one that fixes what was actually reported:
1. --include-comments on `bd list` populates each row's comments with the
full bodies, the list twin of `bd show --include-comments`. Opt-in: it
costs one query per row that has comments.
2. Every row with a nonzero comment_count whose bodies were NOT hydrated now
carries comments_omitted=true, by default, with no flag. A flag nobody
knows to pass does not fix a silent hole; a marker on the row does.
The bodies ride on types.Issue.Comments, which already carried the `comments`
key for export/import and was simply never populated on this path, so the only
new field is the marker.
Hydration is one shared body (workapi.HydrateListComments) called from BOTH
issueops.Reader.List implementations, the store-backed and the unit-of-work
one. Those are separate bodies that have answered one contract method
differently before; it runs in the page epilogue beside FinishPageAt, after the
trim, so a page never pays for rows it is about to drop.
The source parameter is a CONSTRUCTOR rather than a source, and that is
load-bearing. Building the unit-of-work comment source eagerly made a
capability only the opt-in path uses into a requirement every caller had to
satisfy, and turned `GET /v0/beads/issues` into a 500 on a provider without a
comment use case — on requests that had asked for no comments. A count-only
listing now constructs nothing, pinned by a test that fails if the constructor
is called.
Tests pin each implementation separately rather than duplicating: unit tests
over a fake source, an embedded-dolt test over the real CLI on the direct
route, and a proxied-server test over the real CLI on the unit-of-work route.
Sabotage-controlled three ways — no-op the shared body and all three suites go
red; unwire either reader alone and only that reader's CLI test fails, which is
what proves neither integration test is redundant.
Not addressed, deliberately: gt-mfp5 (bd comment does not advance updated_at,
the orthogonal recency axis) and be-ozp (bd ready --json carries no marker; it
does not route through Reader.Ready).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D
Executed-By: beadsrig/polecats/dag
* fix(list): do not read a skipped comment count as proof of no comments (be-73x)
Codex review of the parent commit, correctly.
`IncludeComments: true` combined with `SkipCounts: true` returned a page with
no comment bodies at all — no error, no marker, nothing — while
`IncludeComments` documents a guarantee to populate them. The hydration loop
skipped any row whose CommentCount was zero as an optimisation, and SkipCounts
zeroes every count: `issueops.ListRequest.SkipCounts` says in its own doc that
a zero then means UNKNOWN rather than none.
That is this bead's own failure mode reintroduced one layer down by the fix for
it: a silent, well-formed, empty answer to a request that asked for content.
I had considered the interaction and resolved it wrongly, in a comment reading
"the count is authoritative here because the JSON route never sets SkipCounts".
True of today's CLI callers, and not a property of the contract — issueops
.ListRequest is a PUBLIC request type and permits both fields at once. A
comment saying "X cannot happen because of how callers behave today" on a
public type is a bug with a justification attached, and worse than no comment,
because it tells the next reader the case was checked.
countsKnown is now a parameter rather than an assumption; call sites pass
!req.SkipCounts.
countsKnown true a zero count proves a row has nothing; skip its query.
countsKnown false query every row, because nothing proves otherwise, and
mark no row omitted, because comments_omitted asserts a
nonzero count the page cannot support.
The second half is the mirror defect on the marker path — the same conflation,
the other direction — which the review did not name.
No behaviour change on any current CLI path: the JSON route never sets
SkipCounts, so it passes countsKnown true, and the text route asks for no
comments and marked nothing before either. Verified: `bd list --json` output
identical, and text output identical with and without the flag.
Regression tests HonorsIncludeWhenCountsAreSkipped and
MarksNothingWhenCountsAreSkipped. Sabotage-controlled: restoring the
count-authoritative skip fails the first with "issued 0 comment reads, want 2".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D
Executed-By: beadsrig/polecats/dag
* fix(list): resolve the comment plane by residence, not by the row's flags (be-73x)
Maintainer review fixup for #6473, iteration 1. Both review lanes reached the
same major independently and the synthesizer re-verified it against the tree.
The new list hydration derived the comment table from the row's own
Ephemeral/NoHistory flags - issueops.IsWisp's rule, which is right for routing a
record being WRITTEN and wrong on a read. `bd import` pins a `no_history` record
to the DURABLE table while preserving the flag on the row, because clearing it
would change the content hash and break export->import->export byte-identity,
and every clone materializes its database by importing JSONL. So a promoted
no-history bead that has been through a round-trip is a durable row whose flags
say wisp:
bd list --json --include-comments read wisp_comments, found nothing, and
returned comment_count=N beside an empty
`comments`, with no marker and no error
bd comment, bd show write and read that same row's comments on
the issues plane, by found-table
That is be-73x's own failure mode reintroduced under the flag whose contract is
"gets them or gets an error", and a cross-role divergence: `bd list` and
`bd show` disagreed about one row. The mirror case is real too - an import
record whose `wisp_plane` key pins it to the wisps table with neither flag set
reads back as durable - so no flag-based rule gets both directions right.
The plane now comes from the seam that knows it. HydrateListComments takes a
CommentPlanes lookup instead of inferring; the unit-of-work reader answers it
from the wisps TABLE (IssueUseCase.GetWispsByIDs, the call edgeReader.ReadEdges
already makes for the same question), once per page, inside the page's own read
transaction. The store-backed seam passes SourceRoutesCommentPlanes because its
source routes ids itself (DoltStore.GetIssueComments picks the table from
isActiveWisp) and would buy a lookup for an argument it ignores. isWispPlane is
deleted: nothing on this path infers a plane any more. A nil lookup is an error
rather than a silent "durable", so a third seam has to answer the question
rather than inherit the default this bug was.
A MISSING WISPS TABLE STAYS "NO WISPS" rather than a failed listing, classified
through the same two helpers the counts query that produced the page uses
(dberrors.MissingTableName + sqlbuild.OptionalWispTable). Any other failure of
the lookup fails the call: a guessed plane answers with the wrong table's
contents and nothing in the response shows it.
Tests. The unit table now asserts residence AGAINST the flags, with each row's
comments present only on the plane it lives on, so a wrong-table read shows up
as missing TEXT and not merely as a wrong flag in a recorded call. Restoring the
flag inference reds exactly the two rows where flags and table disagree
(durable-carrying-no_history, wisp-table-carrying-no-flags) and leaves the two
agreeing rows green. The old `override_wins_over_flags` case is gone:
WispPlaneOverride is `json:"-"` and set only by import, in memory, so no scanned
row can carry it and that branch was unreachable on this path - which is what
made the suite look sufficient (Codex's separate minor, folded in here as the
same root cause). New seam-level tests drive the real uow Reader.List over both
shapes, and pin that a listing without the flag resolves no planes at all, that
a missing wisps table is tolerated, and that any other lookup failure
propagates; emptying the residence answer reds the wisp-row leg.
Also from the review, non-gating:
- types.IssueWithCounts.CommentsOmitted and the OpenAPI property stated the
marker rule unconditionally on a type Reader.Ready and the claim response also
return, neither of which calls the epilogue. Both now scope the rule to the
List surfaces and cite be-ozp, which is where the parent commit deliberately
left the ready surfaces. (`bd ready --json` does not route through
Reader.Ready; GET /v0/beads/ready and ClaimNextResponse.claimed do.)
- GET /v0/beads/issues gained no `include_comments` parameter, so its
description now says so and points at the detail read, in the idiom the
`revision` paragraph above it already uses.
- One internal/httpapi list test for the new wire field: the marker present for
a commented row, absent for an uncommented one. It was asserted only by the
spec file; the detail twin has get_issue_test.go. Neutering
markCommentsOmitted reds it.
Validation: go build ./...; go vet over the changed packages and again with
CGO_ENABLED=0; make api-check clean, so the spec edits oblige no regeneration;
go test ./internal/workapi/... ./issueops/... ./internal/types/;
TestBothReaderImplementationsAgreeOnTheListEpilogue plus the new plane tests in
./internal/storage/uow/; BEADS_TEST_PROXIED_SERVER=1
TestProxiedServerListComments 3 PASS and BEADS_TEST_EMBEDDED_DOLT=1
TestEmbeddedListComments 4 PASS.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
669 lines
34 KiB
Go
669 lines
34 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
"time"
|
|
|
|
"github.com/steveyegge/beads/internal/types"
|
|
)
|
|
|
|
// IssueWithCounts is one row of a work page: the issue plus its relationship
|
|
// cardinalities.
|
|
type IssueWithCounts = types.IssueWithCounts
|
|
|
|
// IssueDetails is one issue with its labels, edges and cardinalities.
|
|
type IssueDetails = types.IssueDetails
|
|
|
|
// MolType classifies a molecule.
|
|
type MolType = types.MolType
|
|
|
|
// WispType classifies an ephemeral record.
|
|
type WispType = types.WispType
|
|
|
|
// ReadyRequest describes one ready-work query.
|
|
//
|
|
// It is a HIGH-LEVEL request, not a filter: normalization, alias expansion,
|
|
// validation and defaulting all happen inside the implementation. A caller
|
|
// that wants ready work says what it wants, never how the query is shaped —
|
|
// which is the whole reason two front doors cannot answer this question
|
|
// differently.
|
|
type ReadyRequest struct {
|
|
// IssueType restricts the type. Only shorthand alias expansion is applied
|
|
// (mr, feat, mol, enhancement, dec, adr); an unrecognized type matches
|
|
// nothing rather than failing. Setting it drops the default type
|
|
// exclusions, ExcludeTypes included.
|
|
IssueType string
|
|
// Assignee restricts to one actor. Unassigned wins over a stale Assignee.
|
|
Assignee string
|
|
// Unassigned restricts to rows with no assignee.
|
|
Unassigned bool
|
|
|
|
// Labels must ALL be present; LabelsAny requires at least one;
|
|
// ExcludeLabels must be absent. All three are raw: normalization happens
|
|
// inside.
|
|
Labels []string
|
|
LabelsAny []string
|
|
ExcludeLabels []string
|
|
// LabelPattern is a glob and LabelRegex a regular expression, both matched
|
|
// against labels.
|
|
LabelPattern string
|
|
LabelRegex string
|
|
|
|
// Priority is an exact priority. It is a pointer because 0 is a real
|
|
// priority: a value-plus-flag pair would let one half be filled in without
|
|
// the other, and P0 has already been lost that way once.
|
|
Priority *int
|
|
|
|
// ParentID restricts to recursive descendants of one issue.
|
|
ParentID string
|
|
// MolType restricts to one molecule type.
|
|
MolType *MolType
|
|
|
|
// IncludeDeferred admits rows whose defer_until is still in the future;
|
|
// IncludeEphemeral admits wisp-plane rows.
|
|
IncludeDeferred bool
|
|
IncludeEphemeral bool
|
|
|
|
// ExcludeTypes names types to exclude. Entries may be comma-separated;
|
|
// splitting and alias expansion happen inside. Ignored when IssueType is
|
|
// set.
|
|
ExcludeTypes []string
|
|
|
|
// MetadataFields is a top-level metadata equality filter and
|
|
// HasMetadataKey a top-level key-presence filter. Keys are validated
|
|
// inside.
|
|
MetadataFields map[string]string
|
|
HasMetadataKey string
|
|
|
|
// Sort is the ready ordering: hybrid, priority or oldest. Empty resolves to
|
|
// hybrid at the storage layer, which no front door should rely on — both
|
|
// surfaces send a concrete policy, because hybrid demotes older
|
|
// high-priority work and therefore changes the item SET once Limit
|
|
// truncates.
|
|
Sort string
|
|
|
|
// Limit bounds the page. Nil means the shared ready default; 0 means
|
|
// unlimited. It is a pointer so that "unset" and "explicitly unlimited"
|
|
// stay distinguishable, which is what lets one constant serve both
|
|
// surfaces.
|
|
Limit *int
|
|
// Offset skips the first N matching rows, on EVERY implementation. The
|
|
// page a caller receives is the rows at positions [Offset, Offset+Limit)
|
|
// of the answer the same request returns unpaged, in the same order.
|
|
//
|
|
// WHERE the skip happens is not a backend's choice either. One seam
|
|
// renders OFFSET and one renders LIMIT without it, so both bodies reach
|
|
// past the skipped rows and drop them in the shared page epilogue
|
|
// (internal/workapi.FinishPageAt) — which is also the only sequence that
|
|
// is right for a sort SQL cannot express, since that order first exists
|
|
// after the fetch.
|
|
//
|
|
// An Offset past the end of the result set is an empty page and a nil
|
|
// error, not a failure: a pager that walks off the end has its answer.
|
|
//
|
|
// A ready request carries no keyset position, so there is no portable way
|
|
// to page ready work. A caller that must page across backends pages a
|
|
// ListRequest instead — see ListRequest.Offset.
|
|
Offset int
|
|
|
|
// Brief drops the free-form text from every row: Description, Design,
|
|
// AcceptanceCriteria, Notes, Payload and Waiters come back zero-valued and
|
|
// the row carries types.Issue.IsLitePartial. See ListRequest.Brief, which
|
|
// is the same knob on the other operation and carries the full contract.
|
|
Brief bool
|
|
}
|
|
|
|
// ListRequest describes one issue-list query.
|
|
//
|
|
// Like ReadyRequest it is high-level: the default
|
|
// status/pinned/template/gate/infra exclusions, type validation, status
|
|
// parsing and limit defaulting are all applied inside.
|
|
//
|
|
// PINNED is TWO exclusions rather than one, because a row can be pinned two
|
|
// unrelated ways and each is hidden by its own predicate. The `pinned` STATUS
|
|
// is one of the statuses the default status exclusion covers, alongside
|
|
// `closed`; the separate Pinned FLAG — a marker on a row of any status — is
|
|
// hidden by a predicate of its own. A row carrying either is absent from a
|
|
// default listing, and the knob that takes each back off is a different one:
|
|
// see Status for the first and PinnedFlag for the second.
|
|
type ListRequest struct {
|
|
// Status selects statuses; one name, or a comma-separated OR set. Setting
|
|
// it REPLACES the default exclusions rather than fighting them.
|
|
//
|
|
// It replaces the STATUS ones only. The pinned-flag predicate survives it,
|
|
// so `pinned` and `hooked` are the two spellings that also drop that
|
|
// predicate — every other status narrows to unflagged rows.
|
|
Status string
|
|
// IssueType is validated against the workspace vocabulary — unlike
|
|
// ReadyRequest.IssueType, which matches nothing rather than failing.
|
|
IssueType string
|
|
Assignee string
|
|
TitleSearch string
|
|
SpecPrefix string
|
|
// IDFilter is a comma-separated id set.
|
|
IDFilter string
|
|
|
|
Labels []string
|
|
LabelsAny []string
|
|
ExcludeLabels []string
|
|
LabelPattern string
|
|
LabelRegex string
|
|
|
|
TitleContains string
|
|
DescContains string
|
|
NotesContains string
|
|
ExternalContains string
|
|
ExternalRef string
|
|
|
|
CreatedBefore *time.Time
|
|
CreatedAfter *time.Time
|
|
UpdatedAfter *time.Time
|
|
UpdatedBefore *time.Time
|
|
ClosedAfter *time.Time
|
|
ClosedBefore *time.Time
|
|
DeferAfter *time.Time
|
|
DeferBefore *time.Time
|
|
DueAfter *time.Time
|
|
DueBefore *time.Time
|
|
|
|
EmptyDesc bool
|
|
NoAssignee bool
|
|
NoLabels bool
|
|
SkipLabels bool
|
|
// SkipCounts suppresses the CARDINALITY hydration exactly as SkipLabels
|
|
// suppresses the label one: DependencyCount, DependentCount and
|
|
// CommentCount come back ZERO, and a caller must read a zero as UNKNOWN
|
|
// rather than as none. Nothing else about the page moves — the rows, their
|
|
// order, Parent and the has-more verdict are what they would have been —
|
|
// because this chooses what is HYDRATED, never which rows match.
|
|
//
|
|
// It is here for the renderings that print a page without those three
|
|
// numbers. Each is its own aggregate join, and the reverse-blocker one is
|
|
// the expensive member: it joins on an expression the embedded engine's
|
|
// planner cannot index, which is the per-call cost that makes a counted
|
|
// page the wrong shape for a listing that shows no counts.
|
|
//
|
|
// Like SkipLabels it is NOT carried onto the ReadyFlag arm; the counts are
|
|
// hydrated there either way, which costs time and not correctness.
|
|
SkipCounts bool
|
|
|
|
// IncludeComments populates every row's Issue.Comments with that issue's
|
|
// full comment bodies, and is the LIST twin of GetRequest.IncludeComments.
|
|
// Like SkipLabels and SkipCounts it chooses what is HYDRATED, never which
|
|
// rows match: the rows, their order, Parent and the has-more verdict are
|
|
// what they would have been.
|
|
//
|
|
// IT IS OPT-IN BECAUSE IT COSTS A QUERY PER ROW, which is the same reason
|
|
// the detail view's twin is. A page of 50 is 50 comment reads; a listing
|
|
// asking for the whole store is that many. Nothing hydrates comments
|
|
// unless a caller asks.
|
|
//
|
|
// WHY THE KNOB EXISTS AT ALL (be-73x). comment_count has always been on
|
|
// the row and the bodies never were, so a caller searching a LISTING for
|
|
// text that lives in a comment gets a well-formed, non-empty, WRONG answer
|
|
// — the rows that match are simply absent, and no error, no zero and no
|
|
// short count marks them. That is the failure this knob exists to make
|
|
// answerable, which is why the unhydrated rows also carry
|
|
// types.IssueWithCounts.CommentsOmitted rather than staying silent.
|
|
//
|
|
// IT APPLIES TO BOTH ARMS, ReadyFlag included, and is neither carried nor
|
|
// refused by it: hydration runs in the shared page epilogue after the
|
|
// query, so it is not a filter the ready query has to be able to express.
|
|
//
|
|
// A row whose comments could not be read is an ERROR, not a short list.
|
|
// The detail view's IncludeComments makes the same promise for the same
|
|
// reason: a caller that asked for the rows gets them or gets told.
|
|
IncludeComments bool
|
|
|
|
// Brief suppresses the FREE-FORM TEXT the way SkipLabels suppresses labels
|
|
// and SkipCounts the cardinalities: Description, Design,
|
|
// AcceptanceCriteria, Notes, Payload and Waiters are not selected and come
|
|
// back zero-valued. Nothing else about the page moves — the rows, their
|
|
// order, Parent and the has-more verdict are what they would have been —
|
|
// because this chooses what is HYDRATED, never which rows match. A
|
|
// predicate over a heavy column (DescContains, NotesContains, EmptyDesc)
|
|
// keeps selecting exactly the rows it selects today: WHERE is independent
|
|
// of the SELECT shape.
|
|
//
|
|
// A BLANK FIELD IS AMBIGUOUS ON THE WIRE and the row says so in process:
|
|
// all six are omitempty, so a projected row marshals identically to a
|
|
// genuinely textless one, and the row carries types.Issue.IsLitePartial to
|
|
// tell them apart for an in-process caller. That flag is json:"-", so a
|
|
// wire consumer distinguishes them by having asked — the same shape the
|
|
// repo has already argued about twice (ga-clgh/CommentsOmitted, #5550).
|
|
//
|
|
// UNLIKE SkipLabels and SkipCounts it IS carried onto the ReadyFlag arm,
|
|
// and onto ReadyRequest.Brief beside it. Those two drop a NUMBER the ready
|
|
// renderings print; this drops a body no listing prints, so carrying it is
|
|
// what makes `--ready` and `bd ready` answer the same request the same way.
|
|
//
|
|
// It is the storage layer's types.IssueFilter.Lite / types.WorkFilter.Lite
|
|
// under the name the CLI and the MCP integration already use for a
|
|
// projection (bd show --brief-deps, the MCP's brief).
|
|
Brief bool
|
|
|
|
// Priority is exact; PriorityMin and PriorityMax bound a range. All three
|
|
// are pointers for the same reason ReadyRequest.Priority is.
|
|
Priority *int
|
|
PriorityMin *int
|
|
PriorityMax *int
|
|
|
|
// PinnedFlag and NoPinnedFlag select on the Pinned FLAG, which is not the
|
|
// `pinned` status — see this type's own doc for why there are two of them.
|
|
//
|
|
// PinnedFlag answers with the FLAGGED rows and only them, at any status: it
|
|
// drops the default status exclusions on the way, so a closed pinned row —
|
|
// which a default listing hides twice over — is in that answer.
|
|
//
|
|
// NoPinnedFlag asks for the UNFLAGGED rows, which a default listing already
|
|
// answers with. Its work is holding that predicate in place where AllFlag
|
|
// or a pinned/hooked Status would otherwise have dropped it, so on a
|
|
// default listing it changes nothing and on those it narrows.
|
|
//
|
|
// On the ReadyFlag arm neither applies: that set decides pinned for itself,
|
|
// which is why PinnedFlag is refused there and NoPinnedFlag merely accepted
|
|
// (see AllFlag).
|
|
PinnedFlag bool
|
|
NoPinnedFlag bool
|
|
IncludeTemplates bool
|
|
IncludeGates bool
|
|
IncludeInfra bool
|
|
// IncludeEphemeral admits the EPHEMERAL PLANE — the wisps TABLE, which a
|
|
// default listing does not read at all — and admits nothing else.
|
|
//
|
|
// WHAT IS IN THAT PLANE is not only true ephemerals. The wisps table holds
|
|
// every row the durable plane does not: wisps proper (ephemeral = 1) AND
|
|
// no-history rows, which live there with ephemeral = 0. Both arrive
|
|
// together, because this selects a TABLE rather than testing a column.
|
|
//
|
|
// False, the zero value, is the listing every caller has today: the durable
|
|
// issues table alone. True merges the wisps table IN ADDITION, so under the
|
|
// same filters the answer is a SUPERSET of the false answer. It never
|
|
// narrows, and it never becomes ephemeral-only.
|
|
//
|
|
// IT IS NOT THE SAME MECHANISM AS ReadyRequest.IncludeEphemeral, despite
|
|
// the shared name and the shared "admit in addition" reading, and the
|
|
// difference is observable. The ready query reads BOTH planes either way
|
|
// and its flag adds a per-ROW predicate (ephemeral = 0) when unset; this
|
|
// one selects which TABLES are read at all. So a no-history row — in the
|
|
// wisps table with ephemeral = 0 — is already in a DEFAULT ready answer and
|
|
// is absent from a default listing until this flag is set. Match the two
|
|
// fields for intent, never for row-level equivalence.
|
|
//
|
|
// IT IS A PLANE KNOB, NOT A TYPE KNOB — the difference from the three
|
|
// fields above it. Each of those takes a TYPE exclusion back off; this
|
|
// takes none off, so an ephemeral row whose type a default listing already
|
|
// excludes stays excluded. THAT INCLUDES THE INFRA TYPES, which is the
|
|
// combination most likely to surprise: the configured infra vocabulary
|
|
// (agent, role and message by default) is excluded by TYPE, so ephemeral
|
|
// agent/role/message rows need IncludeInfra as well as — or instead of —
|
|
// this. IncludeInfra does BOTH, which makes it strictly wider; what this
|
|
// field alone reaches is the ephemeral rows of the types a listing already
|
|
// shows.
|
|
//
|
|
// THE MERGED ANSWER IS ONE ORDER. Both planes are ordered together by
|
|
// SortBy as if they were a single table — not the durable rows followed by
|
|
// the ephemeral ones — so a Limit truncates the merged order rather than
|
|
// one plane's. Both implementations produce it (one merge-sorts two ordered
|
|
// legs, the other ORDERs a SQL union), and the keyset position
|
|
// (AfterCreatedAt/AfterID) is applied to BOTH legs, so a paged walk over
|
|
// the merged order drops no row and repeats none.
|
|
//
|
|
// The caveat that walk inherits is the one every multi-page walk already
|
|
// has, and this does not deepen it: a page is not a snapshot. A row written
|
|
// — or, for a wisp, compacted away — between two pages is seen or missed
|
|
// according to where it falls relative to the position, and the ephemeral
|
|
// plane merely turns over faster than the durable one.
|
|
//
|
|
// On the ReadyFlag arm it is CARRIED rather than dropped; see that field.
|
|
IncludeEphemeral bool
|
|
// IncludeAllTypes lifts every default suppression that hides a bead from a
|
|
// listing on account of WHAT IT IS: the three type knobs above (templates,
|
|
// gates, infra types) AND the ephemeral plane, so the wisps table is read
|
|
// too. Frontends whose contract is "never hide a bead" — `bd human list`,
|
|
// where a human label is an explicit request for a person's attention —
|
|
// set this one field instead of enumerating the knobs and then drifting
|
|
// from them when a fourth suppression lands.
|
|
//
|
|
// IT IS THE UNION OF THOSE FLAGS, NOT A NEW MECHANISM. Setting it is
|
|
// equivalent to IncludeTemplates + IncludeGates + IncludeInfra +
|
|
// IncludeEphemeral; it narrows nothing and admits nothing they cannot.
|
|
// Both the type suppressions and the plane decision live in workapi's
|
|
// applyTypeSuppressions, which this flag skips entirely — so a suppression
|
|
// added there is lifted here automatically, which is the whole point.
|
|
//
|
|
// IT SAYS NOTHING ABOUT STATUS. The done/frozen exclusions and the pinned
|
|
// default are a separate axis and still apply; --status (including "all")
|
|
// is how a caller lifts those.
|
|
IncludeAllTypes bool
|
|
// ExcludeTypes entries may be comma-separated; splitting happens inside.
|
|
ExcludeTypes []string
|
|
|
|
ParentID string
|
|
NoParent bool
|
|
MolType *MolType
|
|
// WispType matches the wisp_type COLUMN, which both tables carry. It is
|
|
// therefore a predicate and not a plane selector: it does not admit the
|
|
// ephemeral plane, and on a default listing — where that plane is
|
|
// suppressed — it narrows the durable rows to those whose wisp_type
|
|
// matches, which no ordinary durable row has. The combination that answers
|
|
// with rows is IncludeEphemeral (or IncludeInfra) plus this, and it is
|
|
// lawful rather than refused: the two compose as an ordinary AND, admitting
|
|
// the plane and then narrowing it to one classification.
|
|
WispType *WispType
|
|
|
|
DeferredFlag bool
|
|
OverdueFlag bool
|
|
|
|
// MetadataFields is a top-level metadata equality filter and
|
|
// HasMetadataKey a top-level key-presence filter. Keys are validated
|
|
// inside, as they are for ReadyRequest.
|
|
MetadataFields map[string]string
|
|
HasMetadataKey string
|
|
|
|
// AllFlag drops the default status exclusions.
|
|
//
|
|
// ReadyFlag switches the query to the blocker-aware ready set. It does NOT
|
|
// simply add a blocker predicate to this listing: that query reads a
|
|
// narrower filter vocabulary than this request can describe, and only part
|
|
// of the request reaches it.
|
|
//
|
|
// WHAT IT CARRIES: Status/Statuses (an explicit --status is the
|
|
// intersection; AllFlag and `--status all` still take the open default),
|
|
// IssueType, all five label forms, Assignee, NoAssignee,
|
|
// the exact Priority, ParentID, MolType, WispType, MetadataFields,
|
|
// HasMetadataKey, the type exclusions (ExcludeTypes, and with them
|
|
// IncludeGates and IncludeInfra), IncludeEphemeral — the ready query has an
|
|
// ephemeral gate of its own, so the plane bit crosses intact and
|
|
// IncludeInfra's plane half crosses with it — Limit, Offset and the MaxRows
|
|
// cap with its attribution. SortBy and Reverse
|
|
// still apply, because the display order is applied to the page after the
|
|
// query rather than inside it.
|
|
//
|
|
// WHAT IT REFUSES: every other filter here is one the ready query cannot
|
|
// carry, so combining it with ReadyFlag returns ErrValidation naming the
|
|
// fields rather than answering a wider question than was asked. That is
|
|
// IDFilter, TitleSearch, SpecPrefix, the four *Contains fields,
|
|
// ExternalRef, every Created/Updated/Closed/Defer/Due bound, DeferredFlag,
|
|
// OverdueFlag, EmptyDesc, NoLabels, NoParent, PinnedFlag, PriorityMin,
|
|
// PriorityMax, and the keyset position. There is no fallback: no
|
|
// combination of the two silently widens the answer.
|
|
//
|
|
// TWO THINGS THE READY SET DECIDES FOR ITSELF, which no field here
|
|
// overrides. It never returns pinned issues, which is why NoPinnedFlag is
|
|
// accepted and PinnedFlag refused. And it applies no template predicate at
|
|
// all, so this request's default template exclusion does not reach it and
|
|
// IncludeTemplates changes nothing here: a template is left out of a
|
|
// ReadyFlag listing only when its issue type is one the ready query
|
|
// already excludes. SkipLabels and SkipCounts are likewise not carried —
|
|
// labels and cardinalities are hydrated either way, which costs time and
|
|
// not correctness.
|
|
AllFlag bool
|
|
ReadyFlag bool
|
|
|
|
// SortBy names the display order and Reverse inverts it. A sort the
|
|
// database cannot express (natural-numeric id order) is resolved inside by
|
|
// fetching the full result set and trimming, so no caller has to know
|
|
// which sorts those are.
|
|
SortBy string
|
|
Reverse bool
|
|
|
|
// Limit bounds the page the caller RECEIVES. Nil means the shared list
|
|
// default; 0 means unlimited. The row limit actually pushed into the query
|
|
// is derived from it inside the implementation, together with the
|
|
// over-fetch that detects truncation.
|
|
Limit *int
|
|
// Offset skips the first N matching rows, on EVERY implementation, and the
|
|
// page is the rows at positions [Offset, Offset+Limit) of the answer the
|
|
// same request returns unpaged. See ReadyRequest.Offset for where the skip
|
|
// is applied and why that is not a backend's choice either.
|
|
//
|
|
// THE PORTABLE WAY TO PAGE IS THE KEYSET POSITION below,
|
|
// AfterCreatedAt/AfterID: every implementation honors it, and it does not
|
|
// skip or repeat rows when the result set changes underneath a walk.
|
|
// Offset is here for the surfaces that already published it.
|
|
Offset int
|
|
|
|
// AfterCreatedAt and AfterID carry a decoded keyset position in the
|
|
// (created_at DESC, id ASC) order. The opaque token that encodes them is a
|
|
// transport concern and never reaches this contract.
|
|
//
|
|
// AfterPriority EXTENDS that position to the (priority ASC, created_at
|
|
// DESC, id ASC) order — the order SortBy="priority" and the empty default
|
|
// render — and is honored by every implementation, on BOTH tier legs, the
|
|
// same way the pair above is. It is the same position and not a second
|
|
// one: AfterCreatedAt alone decides whether one was supplied, so a
|
|
// priority with no instant is ignored exactly as an AfterID with no instant
|
|
// is.
|
|
//
|
|
// SET IT ONLY UNDER THE ORDER IT NAMES. A priority position under
|
|
// SortBy="created" positions in an order the ORDER BY does not render, and
|
|
// the page that comes back is a walk through rows neither side agrees on.
|
|
// The order the request asks for and the order the position was minted in
|
|
// are one decision; the transport above this contract is what keeps them
|
|
// from drifting.
|
|
AfterCreatedAt *time.Time
|
|
AfterID string
|
|
AfterPriority *int
|
|
|
|
// MaxRows is a DEFENSIVE CAP rather than a page. It bounds how many rows
|
|
// the query may match before the whole answer is refused; 0 disables it.
|
|
// A request whose result set exceeds it comes back as
|
|
// *internal/storage/issueops.ErrTooManyRows — carrying the count observed,
|
|
// the cap, and MaxRowsSource's attribution — and NO PAGE. That is the
|
|
// difference from Limit, whose overflow is an ordinary truncated page with
|
|
// HasMore set. It is a circuit breaker for a caller that would rather fail
|
|
// than wait. The type is named here rather than left as "an error" so a
|
|
// caller can tell the cap firing from any other failure with errors.As;
|
|
// this leaf does not import it, and no answer depends on that.
|
|
//
|
|
// EVERY IMPLEMENTATION HONORS IT, and they agree on when it fires: when
|
|
// the query matched more rows than the cap allows AND the window the
|
|
// request asked the query to TOUCH could have exceeded it. THAT WINDOW IS
|
|
// Limit+Offset, NOT Limit. A row Offset skips is a row the query matched,
|
|
// so an offset walks a caller toward the breaker and never past it: a cap
|
|
// of Limit+Offset or looser never fires, because a query bounded to that
|
|
// many rows cannot break it, and one more row of offset is what flips the
|
|
// same request to a refusal. The two seams size that window through one
|
|
// function (internal/storage/issueops.SearchProbeLimit) so they cannot
|
|
// disagree about the boundary.
|
|
//
|
|
// Unlike SkipCounts and SkipLabels it IS carried onto the ReadyFlag arm.
|
|
MaxRows int
|
|
// MaxRowsSource attributes the cap to whatever knob set it — "--max-rows",
|
|
// "BEADS_MAX_ROWS", or empty for a library caller — and that attribution is
|
|
// what the refusal text reads back. It decides no answer: a request is
|
|
// refused on MaxRows alone, and this only decides how the refusal reads.
|
|
MaxRowsSource string
|
|
}
|
|
|
|
// GetRequest describes one issue-detail lookup.
|
|
type GetRequest struct {
|
|
// ID is the exact canonical id. There is no fuzzy, prefix or substring
|
|
// resolution here: an interactive affordance that can resolve to a
|
|
// different issue than the caller named has no place on a contract two
|
|
// front doors share. The issue-to-wisp fallback DOES happen inside.
|
|
//
|
|
// THAT FALLBACK NEEDS NO PLANE ORDER, and this contract deliberately
|
|
// states none: no LOCAL WRITE PATH can make an id resident in both planes,
|
|
// so the state an order would arbitrate is not reachable by writing
|
|
// through this library. Every local write path closes it. A guarded create
|
|
// probes BOTH tables before inserting
|
|
// and answers ErrAlreadyExists for an id either one already holds. Every
|
|
// batch create — import, a graph apply, a cooked formula, a markdown
|
|
// import — refuses on top of that an id already resident in the SIBLING
|
|
// table, skipping the row rather than hard-failing only on the
|
|
// auto-import recovery path, which leaves the resident row alone.
|
|
// Promotion and demotion insert into the target plane and delete from the
|
|
// source inside ONE transaction, so their dual-presence window never
|
|
// commits. This is why the implementations are free to probe the planes in
|
|
// either order, and why they in fact differ — a documented non-issue
|
|
// rather than a latent divergence (bd-yby99.22).
|
|
//
|
|
// TWO CAVEATS ARE WORTH CARRYING, and the second is the load-bearing one.
|
|
//
|
|
// First: the graph-apply path served by a unit-of-work provider gets its
|
|
// refusal from a preflight ABOVE storage rather than from the create
|
|
// guard, so a future caller that reached the graph-apply use case directly
|
|
// would be the thing that made this reachable.
|
|
//
|
|
// Second, and NOT closed by anything here: REPLICATION. The durable plane
|
|
// merges from a remote on pull, the ephemeral tables are dolt-ignored and
|
|
// local-only, and no post-merge check reconciles the two — the collision
|
|
// guard is reachable only from the create path. So a clone holding a wisp
|
|
// whose id another clone promoted to durable receives that id into the
|
|
// issues plane while its own wisp row survives. That needs a deterministic
|
|
// id to collide at all, which explicit-id creates and the identically
|
|
// minted infra wisps supply. It is a REAL residual path, it is outside
|
|
// this library's reach, and the resulting state is worse than an
|
|
// unspecified plane order: the merge-based lookups behind ready and search
|
|
// hard-error for the whole store. A plane order here would not rescue it.
|
|
//
|
|
// So the honest statement is the scoped one — no local write path reaches
|
|
// dual residency, replication can, and a caller that hits it has a
|
|
// corrupt store rather than an ordering question (bd-yby99.22).
|
|
ID string
|
|
// IncludeDependents and IncludeComments populate the two expensive row
|
|
// lists. Both default off: the detail view carries counts, and a caller
|
|
// that wants the rows asks for them.
|
|
IncludeDependents bool
|
|
IncludeComments bool
|
|
|
|
// BriefDeps reduces each dependency to its identity-and-shape fields.
|
|
BriefDeps bool
|
|
}
|
|
|
|
// IssuePage is one page of work. Ready and List share it deliberately: both
|
|
// surfaces of both operations emit IssueWithCounts today, and a leaner page
|
|
// type for ready would drift at the field level the moment anything compared
|
|
// the two.
|
|
type IssuePage struct {
|
|
// Items is the page, in the operation's order. Never nil for a successful
|
|
// call.
|
|
Items []*IssueWithCounts
|
|
// HasMore reports that the limit truncated the result.
|
|
HasMore bool
|
|
}
|
|
|
|
// Reader describes guarded issue queries: the read counterpart of Lifecycle,
|
|
// and — like Lifecycle — a role with its own accessor. A new capability gets a
|
|
// new role interface and its own accessor; never append a method here.
|
|
//
|
|
// Each method takes the whole request and performs filter and default
|
|
// construction INTERNALLY. A caller of this interface can only say
|
|
// rd.List(ctx, req): the four-step ritual of building a config source, loading
|
|
// config, building a filter and executing it is not reachable through it.
|
|
// Implementations never mutate caller-owned request values.
|
|
//
|
|
// WHERE THAT IS ENFORCED, precisely, because the difference matters:
|
|
//
|
|
// - The HTTP surface is on the role for all three of its issue reads, and
|
|
// two lint rules make writing a filter there a lint failure rather than a
|
|
// review comment. THE CLAIM at the bottom of this comment names them, and
|
|
// names what they cover and what they do not.
|
|
//
|
|
// - `bd show --json`'s DETAIL VIEW is on the role on BOTH routes: the direct
|
|
// one reaches it through store.IssueReader(), the proxied one through the
|
|
// unit-of-work provider's accessor. Its ALTERNATE views are not, and are
|
|
// not the same question: --refs, --children, --thread and --as-of each
|
|
// answer with their own shape, which this contract does not describe and
|
|
// no HTTP operation serves. --short is not either; it prints one line from
|
|
// the issue, not a detail view.
|
|
//
|
|
// The shared implementation behind the store accessor
|
|
// lives in internal/workapi/storereader, which the
|
|
// cmd-bd-role-constructors depguard rule keeps out of cmd/bd: the
|
|
// accessor is where each storage decorator adds its layer, so a command
|
|
// that constructed a reader directly would get an unspanned one. `bd show`
|
|
// keeps its own id RESOLUTION — fuzzy ids, cross-repo routing, --current —
|
|
// and hands this contract the canonical id it resolved, because an
|
|
// affordance that can answer with a different issue than the caller named
|
|
// has no place on a contract an unattended HTTP client also calls.
|
|
//
|
|
// - `bd list` IS, on both routes, for its PAGE — every output mode but the
|
|
// two named next. --json and every text rendering call List below and
|
|
// nothing else; --ready is not a route of its own on either side, it is
|
|
// ReadyFlag, and picking the ready query from it is this role's job.
|
|
// The two exceptions consume the FILTER as a VALUE and no page can express
|
|
// either: --watch re-runs it on a ticker, and the hierarchical --parent
|
|
// tree re-parents a copy of it at every level. What is NOT an exception,
|
|
// though it looks like one, is the whole-graph dependency-record load
|
|
// behind --format and the pretty tree: that is a different question from
|
|
// both this role's and BlockingAnnotator's, so those renderings take their
|
|
// page from here and load the graph beside it.
|
|
//
|
|
// The other thing `bd list` used to do here was the per-page blocking
|
|
// decoration, which is issueops.BlockingAnnotator's on both routes now —
|
|
// its own role, because it is a DERIVED annotation over ids a page already
|
|
// chose rather than a page.
|
|
//
|
|
// - `bd ready` is NOT, on either route, and will not be until there are more
|
|
// roles to route it through. It consumes the FILTER itself for --claim,
|
|
// --gated, --explain and --mol. Two of its questions HAVE left the filter
|
|
// behind, each for the role that owns it: --claim is ReadyClaimer's, and
|
|
// the published total is ReadyCounter's, on both routes.
|
|
//
|
|
// WHAT `bd ready` DOES SHARE, stated exactly, because "not on the role" is not
|
|
// the same as "unprotected":
|
|
//
|
|
// - CONSTRUCTION. Every route, and both implementations of this interface,
|
|
// build from these same request types through the same two builders in
|
|
// internal/workapi, which the builders' golden files pin.
|
|
// - EXECUTION, on the PROXIED route only. The direct route keeps an epilogue
|
|
// of its own and cannot give it up: it answers the strictly larger question
|
|
// "how many rows did the limit hide" and publishes the total in its
|
|
// pagination meta, where this role answers only "were any hidden".
|
|
// Collapsing them would change one surface's published output. That second
|
|
// question is not off-role, though — it is ReadyCounter's, which both
|
|
// routes now ask through their own accessor, over this same ReadyRequest;
|
|
// what stays outside this role is the PAGE's epilogue, not the count beside
|
|
// it.
|
|
//
|
|
// THE CLAIM, stated once and in full so it can be checked sentence by
|
|
// sentence. SHARED: all three issue reads on the HTTP surface go through this
|
|
// role, so does `bd show --json`'s detail view on both its routes, and so does
|
|
// `bd list`'s page on both of its — in every mode but --watch and the
|
|
// hierarchical --parent tree, which take the filter instead. `bd ready` is not
|
|
// on it and shares instead the request types above, the two builders in
|
|
// internal/workapi that their golden files pin, and workapi.FinishPage on its
|
|
// proxied route only. ENFORCED,
|
|
// and by what: depguard (httpapi-transport-boundary) denies internal/workapi
|
|
// from every non-test file of internal/httpapi, so no builder is callable
|
|
// there, and a forbidigo rule denies naming types.IssueFilter or
|
|
// types.WorkFilter there at all, so no filter is writable there either — both
|
|
// are directory-scoped with no per-file exception, so a file added to that
|
|
// package tomorrow is covered the moment it exists. That same forbidigo rule
|
|
// covers cmd/bd deny-by-default with 59 named exceptions, so the files
|
|
// implementing `bd list` and `bd show` cannot write a filter, and neither can
|
|
// a file they are split or renamed into unless the new name lands on that
|
|
// list. NOT ENFORCED: the rule forbids NAMING those types, not holding a
|
|
// value, so the property is "no filter is written there", not "every filter
|
|
// there came from a builder"; test files are exempt from both rules, because
|
|
// the oracles hold filters in order to inspect them; `bd ready`'s files are
|
|
// among the 59, since its listing and --claim are handed the filter itself and
|
|
// the blocked-issue views in those files name one directly, so it is guarded by
|
|
// the builder and the golden files and not by the linter;
|
|
// cmd/bd/list_show_filter_modes.go is among them too and STAYS there — the
|
|
// count did not drop with this flip, because that file is where `bd list`'s
|
|
// two filter-consuming modes and `bd show --current` live and all three still
|
|
// need to name the type;
|
|
// GET /healthz and GET /v0/beads/context are not issue queries and are on no
|
|
// role; `bd ready`'s direct route and `bd list`'s hierarchical tree run
|
|
// epilogues of their own; and none of this is a merge gate — the rules run in
|
|
// `make ci-pr-lint` on every pull request and aggregate into the ci-gate job,
|
|
// but main carries no branch protection beyond deletion and non-fast-forward,
|
|
// so no check is GitHub-required and a red gate binds by convention.
|
|
//
|
|
// Closing the rest needs more roles (a claim role, an explain role), not more
|
|
// methods here.
|
|
type Reader interface {
|
|
// Ready returns unblocked open work in the requested policy's order.
|
|
Ready(ctx context.Context, req ReadyRequest) (IssuePage, error)
|
|
// List returns issues under the request's filters, in the requested
|
|
// display order.
|
|
List(ctx context.Context, req ListRequest) (IssuePage, error)
|
|
// Get returns one issue's detail view. A miss — for both the issue and the
|
|
// wisp table — is ErrNotFound; a backend failure passes through unchanged
|
|
// and never decays into not-found.
|
|
Get(ctx context.Context, req GetRequest) (*IssueDetails, error)
|
|
}
|