* feat(http): serve IsBlockedBatch through the BlockingAnnotator role behind dependencies.blocking.isBlocked
gc's native ready cache needs bd's stored, transitive is_blocked column for
the active set (beads.BlockedQuerier.IsBlockedBatch). Over http the client
answered it with the generated stub, so every reconcile logged
`operation "IsBlockedBatch" not supported by the http backend`, the
projection stayed disabled and native Ready took ~5 s on the MC shadow.
No read a deployed (1.3.0) server serves can answer the column exactly:
the /v0 reads hydrate issues without is_blocked, the blocking decoration is
direct and two edge types only, and the flag also propagates down
parent-child edges and reads waits-for / conditional-blocks gates. So this
is an additive server behaviour plus a token, not a client-side
composition.
- issueops: BlockingRequest.IncludeIsBlocked asks for, and
IssueBlocking.IsBlocked carries, each answered id's stored flag (nil =
no row, never "free"). issueops.BlockedFlags is the one library entry
for the batched read over the role, chunked at BlockedFlagsChunk (100,
held equal to the served issue_id bound by an httpapi test).
- Bodies: storage/issueops.ExecuteBlockingAnnotation reads the flag with
IsBlockedBatchInTx in the same read transaction (dolt, embeddeddolt and
every sqlkit-style store that calls it); the unit-of-work body asks the
new DependencyUseCase/Repository IsBlockedBatch (same shared SQL body).
externaldeps keeps IsBlockedBatch's external-blocker invariant on the
local and remote annotators, and its Store.IsBlockedBatch no longer makes
the raw edge read over a role-served store.
- Wire: GET /v0/beads/dependencies/blocking accepts `is_blocked` behind the
new behaviour token dependencies.blocking.isBlocked (spec, apigen,
wire-shape golden). wire_revision stays 2.
- Client: httpBlockingAnnotator forwards IncludeIsBlocked and refuses it
BEFORE dialing with *ErrUnsupported{Capability:
dependencies.blocking.isBlocked} against a server that does not
advertise it; Store.IsBlockedBatch is issueops.BlockedFlags over that
annotator, so gc's errors.As latch still sees the typed refusal on an
old server, now naming the token that lifts it.
Tests: conformance case RunBlockingAnnotatorReportsTheTransitiveBlockedFlag
(child of a blocked parent is blocked, free is false, a ghost has no flag,
unasked carries none, BlockedFlags agrees) on the dolt, embedded, uow and
served legs; httpapi handler and chunk-bound tests; client tests for
chunking, the wire shape and the zero-dial refusal; vocabulary/capability
gates.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(externaldeps): keep the external blocker on the unit-of-work IsBlockedBatch
bd serve on a server or proxied-server workspace serves through the
unit-of-work arm (WrapUOWProvider) and advertises
policy.external_dependencies, so a client trusts the server's answers and
adds no external term of its own. That arm's dependency use case did not
override IsBlockedBatch, so the new dependencies.blocking.isBlocked flag
answered the stored is_blocked column, which has no external term. An issue
blocked only by an unsatisfied external: ref came back is_blocked=false,
with that ref listed in its own blocked_by, while GET /v0/beads/ready
excluded it.
dependencyUseCase.IsBlockedBatch now raises every id that has an
unsatisfied external blocker, deciding by the edges and resolver
GetReadyWork excludes by, read through the same unit of work. Unlike Ready
it resolves only the refs of the ids the column answered: a client asks in
chunks, and no chunk should reopen every foreign project the workspace
names. An id naming no row stays absent.
Also correct the store decorator's IsBlockedBatch doc (the served flag now
comes from the annotator role), add the CHANGELOG entry for the new
capability, and pin the flag against Ready on every arm: WrapUOWProvider,
directly and through its BlockingAnnotator (an absent id stays absent), the
local annotator, and the served test, which now asserts the flag and the
batched read. A counting opener pins that the unit-of-work read opens only
the foreign projects its asked rows name.
Checked against a real bd serve on a proxied-server workspace. At
97bcb57738 an issue blocked by external:remote:payments answered
is_blocked=false while /ready excluded it. With this change it answers
true, and once the capability ships /ready includes the issue and
is_blocked is false. Asked about a free issue alone, the server resolves
no external project; asked about the remote-blocked issue, it resolves
remote and leaves alone the unconfigured project another issue names.
Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(externaldeps): pin that a satisfied external blocker leaves the unit-of-work is_blocked false
Review of 192b73676 (bee-ghosttrack): the two new IsBlockedBatch tests only
had unsatisfied external refs, so a body that raised every answered id with
any external record (ignoring the resolver) stayed green.
TestWrapUOWProviderBlockedFlagResolvesOnlyTheAskedRefs's opener now
returns a foreign store whose labelled index carries a CLOSED provider of
provides:payments (the decorator_test.go shape). be-shipped blocks on
external:remote:payments (satisfied) and must read false; be-blocked moves
to external:remote:invoices (still unsatisfied) and reads true; both still
open /projects/remote once. With the reviewer's mutant applied
(`if _, ok := answered[id]; ok && len(state.refsByIssue) >= 0 {`) the test
fails on be-shipped in both new cases; restored, it passes
(bazel test //internal/storage/externaldeps:externaldeps_test).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(externaldeps): pin the store arm's satisfied external ref and the unasked is_blocked flag
The store arm decides an external blocker in two places: IsBlockedBatch's
local loop skips a ref the resolver reports satisfied, and the
BlockingAnnotator role folds IsBlocked's verdict, which applies the same
filter, into the served flag. Both annotators, store and remote, add that
flag only when the request asks for it. No test checked either store answer
for a ref whose project had shipped the capability, or that an unasked
annotation carries no flag, so dropping any of those checks left the
package green.
Pin them: IsBlockedBatch and the store annotator answer false for a row
whose only blocker is external:remote:payments once remote has closed its
provides:payments issue, and neither annotator flags a row unasked, even
one an external ref blocks. This is the store half of bd-yewju3; the
previous commit pinned the unit-of-work half.
Each mutant below survives the package at the previous commit and fails
exactly one test here (go test -tags=gms_pure_go
./internal/storage/externaldeps/; unmutated, bazel test
//internal/storage/externaldeps:externaldeps_test passes):
- decorator.go IsBlockedBatch: `&& !satisfied[dep.DependsOnID]` made
`&& len(satisfied) >= 0` fails TestIsBlockedBatchHonorsShippedExternalRef.
- decorator.go IsBlocked: `if !satisfied[ref.raw] {` made always true fails
TestBlockingAnnotatorLeavesShippedExternalRefUnblocked.
- role_accessors.go: `if req.IncludeIsBlocked {` made `if true {` fails
TestBlockingAnnotatorAddsNoFlagUnasked.
- remote_roles.go: dropping `req.IncludeIsBlocked &&` fails
TestRemoteBlockingAnnotatorMergesExternalBlockers.
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 <noreply@anthropic.com>
231 lines
11 KiB
Go
231 lines
11 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
)
|
|
|
|
// BlockingRequest describes one blocking-annotation read over the ids of a page
|
|
// that has already been fetched.
|
|
//
|
|
// It is a BATCH request in the same sense EdgeReadRequest is: the question is
|
|
// asked about a whole page at once, because that is what a renderer needs and
|
|
// because asking it per row would cost one round trip per row.
|
|
type BlockingRequest struct {
|
|
// IDs are the ids to annotate, each an EXACT canonical id. There is no
|
|
// fuzzy, prefix or substring resolution here, for the reason
|
|
// EdgeReadRequest.IDs gives: an affordance that can answer ABOUT A
|
|
// DIFFERENT ISSUE than the caller named has no place on a contract an
|
|
// unattended client calls.
|
|
//
|
|
// AN EMPTY ENTRY IS ErrValidation. The empty string names nothing a caller
|
|
// can have meant, and an annotation keyed by name has nowhere to put a
|
|
// nameless row.
|
|
//
|
|
// AN EMPTY SLICE IS NOT AN ERROR: it asks about no ids and the answer is no
|
|
// annotations, for the reason EdgeReadRequest.IDs and Counter both give.
|
|
//
|
|
// REPEATS COLLAPSE, at the position of the first mention, exactly as they do
|
|
// for EdgeReadRequest: the answer is keyed by id and a second entry for the
|
|
// same key carries no second fact.
|
|
IDs []string
|
|
|
|
// IncludeIsBlocked asks for each answered id's stored, TRANSITIVE
|
|
// is_blocked flag (IssueBlocking.IsBlocked) alongside the decoration. It
|
|
// is opt-in because the flag is a separate read and a listing that only
|
|
// prints the decoration has no use for it.
|
|
//
|
|
// It is the batched readiness projection a cache needs to answer Ready
|
|
// with the store's own predicate: the column GetReadyWork filters on,
|
|
// which propagates DOWN parent-child edges and reads waits-for and
|
|
// conditional-blocks gates, so BlockedBy (two edge types, direct only)
|
|
// cannot stand in for it. BlockedFlags is the one entry that asks for it.
|
|
IncludeIsBlocked bool
|
|
}
|
|
|
|
// IssueBlocking is one issue's blocking decoration.
|
|
//
|
|
// The json tags are the wire names: this struct IS the element
|
|
// GET /v0/beads/dependencies/blocking emits, so there is no second shape for
|
|
// the same fact.
|
|
type IssueBlocking struct {
|
|
// ID is the annotated id, spelled exactly as the request spelled it.
|
|
ID string `json:"id"`
|
|
// BlockedBy are the OPEN issues this one is blocked by: the targets of its
|
|
// `blocks` edges whose own status is not closed.
|
|
//
|
|
// Never nil for a successful call, so a caller that marshals it emits an
|
|
// empty array rather than null.
|
|
BlockedBy []string `json:"blocked_by"`
|
|
// Blocks are the issues this one blocks: the sources of the `blocks` edges
|
|
// pointing AT it. It is empty when this issue is itself closed, which is
|
|
// the same rule BlockedBy applies from the other end — an edge is live
|
|
// exactly when its blocker is open — stated twice because the two arms read
|
|
// the status of different rows to decide it.
|
|
//
|
|
// Never nil for a successful call.
|
|
Blocks []string `json:"blocks"`
|
|
// Parent is this issue's parent id, or empty when it has none and when the
|
|
// parent it has is closed.
|
|
//
|
|
// AT MOST ONE is reported. The schema permits an issue to carry several
|
|
// `parent-child` edges, and this role reports one of them; WHICH one is not
|
|
// specified here, because both implementations reduce to a single parent
|
|
// before this contract sees the rows and neither picks deliberately. A
|
|
// caller that needs every structural edge asks EdgeReader, which answers
|
|
// with the rows.
|
|
Parent string `json:"parent,omitempty"`
|
|
// IsBlocked is the issue's stored, transitive is_blocked flag — the same
|
|
// value storage's IsBlockedBatch answers and GetReadyWork filters on. It
|
|
// is set only when the request asked (BlockingRequest.IncludeIsBlocked)
|
|
// and the id names a row in either plane; it is nil otherwise, and nil
|
|
// never means "not blocked". An unsatisfied external blocker sets it,
|
|
// exactly as it does for storage's IsBlockedBatch.
|
|
IsBlocked *bool `json:"is_blocked,omitempty"`
|
|
}
|
|
|
|
// BlockingResult is the per-id answer.
|
|
type BlockingResult struct {
|
|
// Items carries one entry per DISTINCT requested id, in the order the
|
|
// request first named it. It is never nil for a successful call, and it is
|
|
// a slice rather than three maps for the reason the three maps are the
|
|
// shape this role replaces: a caller handed BlockedBy, Blocks and Parent
|
|
// separately can be handed two of them, and an id present in one and absent
|
|
// from another says nothing a reader can act on.
|
|
Items []IssueBlocking
|
|
}
|
|
|
|
// BlockingAnnotator describes the DERIVED blocking decoration a listing prints
|
|
// beside each row — `(parent: X, blocked by: Y, blocks: Z)` — and, like
|
|
// EdgeReader, 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 NOT EdgeReader, and the two are deliberately separate (the design pass
|
|
// asked and the answer was two roles, not one). EdgeReader answers with the
|
|
// STORED ROWS: every edge type, targets spelled as stored including
|
|
// `external:` references and ids belonging to another repository, no status
|
|
// consulted, and a per-anchor Missing flag from an existence probe. This role
|
|
// answers a DERIVED, BEST-EFFORT summary: two edge types out of the whole
|
|
// vocabulary, closed blockers dropped, the inbound direction included, ids and
|
|
// nothing else. Merging them would give one role two answer shapes and two miss
|
|
// policies, which is the accretion the governing rule exists to stop.
|
|
//
|
|
// IT IS NOT Reader GROWTH either. Reader.List answers with a PAGE — rows, an
|
|
// order, a limit and a has-more verdict. This is an annotation OVER a page that
|
|
// has already been chosen: it has no order of its own, nothing it returns
|
|
// depends on how the page was selected, and a caller holding ids from anywhere
|
|
// can ask it. A ListRequest field would have implied the annotation was part of
|
|
// the query, and a page fetched with a cap or a cursor would then carry a knob
|
|
// that decides nothing.
|
|
//
|
|
// THERE IS NO MISSING FLAG, which is the sharpest difference from EdgeReader
|
|
// and it is a decision rather than an omission. This role runs no existence
|
|
// probe: an id that names nothing and an id with no live blocking edges
|
|
// decorate identically — nothing is printed beside either — so the probe would
|
|
// be a read whose answer no caller can use. A front door that needs to know
|
|
// whether an id exists asks Reader.Get or EdgeReader, both of which say.
|
|
//
|
|
// BEST-EFFORT MEANS THE ANSWER IS DERIVED, NOT THAT IT MAY BE WRONG. Every
|
|
// promise below holds; what "best-effort" names is the standing the annotation
|
|
// has at a front door, which prints it beside a row and never decides anything
|
|
// on it. What a front door does with a FAILURE is its own policy and not this
|
|
// contract's — and `bd list`'s two routes do not agree on it today: the direct
|
|
// one renders the page undecorated and the proxied one fails the command. This
|
|
// role reports its failures either way; converging the two is a behavior
|
|
// question recorded for the owner as A-blk-1.
|
|
//
|
|
// A BLOCKER THIS DATABASE HOLDS NO ROW FOR COUNTS AS OPEN. An `external:`
|
|
// reference, an id in another repository's namespace, and an id whose issue was
|
|
// deleted out from under its edges are all statuses this store cannot read, and
|
|
// an unreadable status is not `closed`. So such an edge still blocks. That is
|
|
// the conservative reading — a listing that hid a blocker it could not resolve
|
|
// would report work as unblocked on the strength of a row it never found — and
|
|
// it is the behavior both implementations already have.
|
|
//
|
|
// BOTH PLANES ARE ONE GRAPH here, as they are for EdgeReader: a durable issue
|
|
// blocked by a wisp is reported blocked, and a wisp is annotated from the
|
|
// ephemeral dependency tier.
|
|
//
|
|
// THE ORDER WITHIN BlockedBy AND Blocks IS PINNED: ascending by id, with
|
|
// repeats collapsed. It is pinned rather than left to the query because both
|
|
// lists are joined into one line of output, so the query's natural order is
|
|
// user-visible; and repeats collapse because an id can be reached through
|
|
// either dependency tier and a caller counting the entries would otherwise
|
|
// count one edge twice.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply validation and normalization only to
|
|
// attempt-local clones. BlockingRequest travels by value, so IDs is the one
|
|
// member a body could write through to the caller: reading it into a set is
|
|
// fine, sorting or de-duplicating it in place is not.
|
|
//
|
|
// Annotating 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.
|
|
type BlockingAnnotator interface {
|
|
// AnnotateBlocking returns each id's blocking decoration.
|
|
//
|
|
// The outbound edges, the inbound edges and the statuses that decide which
|
|
// of them are live are read from ONE consistent view, so an answer cannot
|
|
// report an issue blocked by a row that a later read in the same call would
|
|
// have found closed. That is the same promise EdgeReader makes for its
|
|
// probe and its edge read, and it is why this is one method rather than a
|
|
// caller's edge read followed by a caller's status lookup.
|
|
//
|
|
// A request naming only ids that are not there is a successful call whose
|
|
// every entry is bare: there is no ErrNotFound on this role, for the reason
|
|
// there is no Missing flag on it.
|
|
AnnotateBlocking(ctx context.Context, req BlockingRequest) (BlockingResult, error)
|
|
}
|
|
|
|
// BlockedFlagsChunk is how many ids BlockedFlags names per AnnotateBlocking
|
|
// call. It equals the served listBlockingAnnotations bound (100 issue_id
|
|
// values; httpapi's maxDependencyAnchors, held equal by a test there), so a
|
|
// call through any transport stays inside a question the server accepts.
|
|
const BlockedFlagsChunk = 100
|
|
|
|
// BlockedFlags answers the batched transitive is_blocked read (storage's
|
|
// IsBlockedBatch: id -> flag, an id naming no row absent) through the
|
|
// BlockingAnnotator role with IncludeIsBlocked, BlockedFlagsChunk ids per
|
|
// call. It is the one library entry for that read on a role-served backend:
|
|
// the http client's IsBlockedBatch is this function over its annotator.
|
|
//
|
|
// Repeats and blank entries are dropped before asking (a blank id names no
|
|
// row, so it would be absent either way). An annotator that answers an item
|
|
// without a flag for an id it reports is treated as "no row", matching the
|
|
// absent-means-not-found contract; a failure of any chunk fails the call.
|
|
func BlockedFlags(ctx context.Context, annotator BlockingAnnotator, ids []string) (map[string]bool, error) {
|
|
out := make(map[string]bool, len(ids))
|
|
distinct := make([]string, 0, len(ids))
|
|
seen := make(map[string]struct{}, len(ids))
|
|
for _, id := range ids {
|
|
if id == "" {
|
|
continue
|
|
}
|
|
if _, dup := seen[id]; dup {
|
|
continue
|
|
}
|
|
seen[id] = struct{}{}
|
|
distinct = append(distinct, id)
|
|
}
|
|
for start := 0; start < len(distinct); start += BlockedFlagsChunk {
|
|
end := min(start+BlockedFlagsChunk, len(distinct))
|
|
result, err := annotator.AnnotateBlocking(ctx, BlockingRequest{
|
|
IDs: distinct[start:end],
|
|
IncludeIsBlocked: true,
|
|
})
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
for _, item := range result.Items {
|
|
if item.IsBlocked == nil {
|
|
continue
|
|
}
|
|
if _, asked := seen[item.ID]; !asked {
|
|
continue
|
|
}
|
|
out[item.ID] = *item.IsBlocked
|
|
}
|
|
}
|
|
return out, nil
|
|
}
|