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 ALL TRANSITIVE DESCENDANTS of one issue, not just // its direct children: internal/storage/issueops/ready_work.go calls // GetDescendantIDsInTx(ctx, tx, *filter.ParentID, 0), the recursive walk. // GH#3396: this used to be a one-hop subquery against the dependency // table, so grandchildren were silently dropped despite this comment and // the help text both promising "descendants (recursive)" — do not // mistake this for ListRequest.ParentID's non-walking clause, which is a // DIFFERENT query (PR #7199 review: an earlier pass here wrongly copied // that one-level wording onto this field). 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 restricts to one issue's children through one SQL clause, the // same one CountRequest.ParentID compiles to // (internal/storage/sqlbuild/filter.go): a parent-child dependency edge // onto ParentID, OR, for a row with no parent-child edge at all, an id // under ParentID's dotted prefix ("X.1", "X.1.1"). NEITHER ARM WALKS. The // edge arm stops at one level, so a grandchild with an edge of its own is // not in the answer, while the prefix arm reaches every edge-less dotted // id at any depth (backend/conformance/reader_contract.go pins that arm). // It is NOT the recursive descendants walk — that is ReadyRequest.ParentID // above, a DIFFERENT field on a different request, backed by // GetDescendantIDsInTx (GH#3396); on the ReadyFlag arm this field crosses // to that query and resolves recursively there. // The recursive tree that `bd list --parent X` renders by DEFAULT comes // from cmd/bd/list_show_filter_modes.go's findAllDescendants re-running // this clause against the store once per level and accumulating the // results client-side, not from this field answering a deeper question. // --flat, --json and --format skip that walk and return exactly this // field's answer, which is why the flat listing is the invocation that // agrees with `bd count --parent X`'s cardinality. // // NoParent restricts to rows with no parent-child dependency edge. It has // no dotted-id arm, so an edge-less "X.1" matches BOTH ParentID X and // NoParent. The ReadyFlag arm refuses it; see that field. 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) }