package issueops import ( "context" "github.com/steveyegge/beads/internal/types" ) // Dependency is one stored dependency edge, exactly as the database holds it: // a source id, a target id, a type and the edge's own annotations. // // It is the ROW and not a view of it, which is what makes this role different // from Relations. A target may be an "external:" reference or an id belonging // to ANOTHER repository — DependencyEditor accepts both — and this database // holds no issue for either. Relations drops such an edge, because it answers // with the issue on the far end and there is none. Here the edge IS the answer, // so it is returned with its target spelled as stored and nothing looked up. // // The ID field is EMPTY on everything this role returns. The source-keyed read // behind it selects the six wire columns and not the row's surrogate key (see // types.Dependency.ID, which says so), so a caller must not use it to tell two // edges apart; the (IssueID, DependsOnID, Type) triple is what identifies an // edge here. type Dependency = types.Dependency // EdgeReadRequest describes one raw-edge read over several anchors at once. // // It is a BATCH request in the sense that batching is the question rather than // an optimization of it: `bd dep list a b c` asks what each of three named // issues depends on, and answers per source. Asking the same question three // times would give three answers a caller then has to key and merge, and would // cost three round trips where the storage seam offers one. type EdgeReadRequest struct { // IDs are the anchors, each an EXACT canonical id. // // EXACT is a promise this role keeps rather than an obligation it puts on // the caller, for the reason RelatedRequest.ID gives: a case variant, an id // carrying surrounding whitespace, a prefix of a real id and a real id with // a suffix are all misses, because an affordance that can answer ABOUT A // DIFFERENT ISSUE than the caller named has no place on a contract an // unattended client calls. A front door that wants partial-id resolution // resolves BEFORE it calls, which is also what lets a routed anchor be // resolved against the store that actually holds it. // // A miss is PER ANCHOR and is reported on that anchor rather than failing // the call — see AnchorEdges.Missing. That is the whole difference in miss // semantics between this role and Relations, which is anchored on one issue // and answers ErrNotFound. // // AN EMPTY ENTRY IS ErrValidation, not a ghost. The empty string names // nothing a caller can have meant, and reporting it as a missing anchor // would put a nameless row in an answer keyed by name. // // AN EMPTY SLICE IS NOT AN ERROR: it asks about no anchors and the answer // is no anchors, for the reason Counter answers 0 rather than refusing an // empty predicate. A caller looping over a list it filtered to nothing // should not have to special-case the empty case to avoid an error. // // REPEATS COLLAPSE. An id named twice is one anchor, at the position of its // first mention: the answer is keyed by anchor, and a second entry for the // same key carries no second fact — it would only invite a caller // aggregating the result to count the same edges twice. IDs []string // Types restricts the answer to these edge types. Empty means every type. // // An entry is checked for being a value at all — non-empty, within the // column's length — and NEVER for membership of a known-types list, exactly // as RelatedRequest.Types is: the vocabulary is OPEN, so a workspace's own // type has to be able to filter. An unusable entry is ErrValidation rather // than a filter that quietly matches nothing. // // The filter narrows EDGES, never anchors. An anchor whose every edge the // filter rejects comes back present with no edges, which is a different // fact from an anchor that is not there. Types []DependencyType } // AnchorEdges is one anchor's stored outgoing edges, or the report that the // anchor is not there. type AnchorEdges struct { // ID is the anchor, spelled exactly as the request spelled it. ID string // Edges are the anchor's stored outgoing edges — the rows whose source is // this anchor — after the request's type filter. // // THE ORDER IS PINNED: ascending by target id, with the edge type breaking // a tie. It is pinned rather than left to the query for the reason // Relations pins its own order: the rows come from one of two dependency // tables depending on which plane the anchor lives on, so the natural order // is an artifact of that placement — stable enough to look deliberate and // not stable enough to rely on. // // The tiebreaker is a TOTALITY guarantee rather than an observable one: the // stores hold at most one edge per (source, target) pair — a second one // with a different type is refused, not added — so no answer reaching a // caller today has two edges to break a tie between. It is stated because // the order must be total whatever the schema later permits, and it is // stated as unreachable so nobody writes a test that cannot be built. // // It is never nil for a successful call, so a caller that marshals it emits // an empty array rather than null. Edges []*Dependency // Missing reports that no issue and no wisp carries this id. // // It exists because an empty edge list is otherwise indistinguishable from // a typo, and the empty list is the COMMON case — most issues depend on // nothing — so the typo would never surface. That is the same reason // Relations probes its anchor's existence; the difference is only that a // batch cannot answer ErrNotFound without discarding the anchors it did // find. // // A missing anchor carries no edges. The converse does not hold: an anchor // that is present with no edges, and one whose edges the type filter // removed, both report false with an empty list. // // DANGLING EDGES ARE NOT MISSING ANCHORS. This flag is about the SOURCE. // An edge whose TARGET names nothing — an external reference, a // foreign-repository id, or a row left behind by a deleted issue — is // returned as stored, and nothing here reports on it: the target is not an // anchor of this request and the role does not probe it. Missing bool } // EdgeReadResult is the per-anchor answer. type EdgeReadResult struct { // Anchors 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 a map because the request's order is part of the // answer: both front doors print the anchors in the order the caller named // them, and a map would have made that ordering each surface's own // invention. Anchors []AnchorEdges } // EdgeReader describes reading STORED DEPENDENCY EDGES for several anchors at // once: the answer `bd dep list a b c` gives, and — like Relations — a role // with its own accessor. A new capability gets a new role interface and its own // accessor; never append a method here. // // IT IS ITS OWN ROLE RATHER THAN A SECOND Relations METHOD, and the reason is // worth stating because the two roles look alike from a distance. Relations is // SINGLE-ANCHOR and answers with HYDRATED ISSUES: its result is the issue on // the far end of each edge, carrying that issue's title, status and priority, // and an edge with no far end in this database is silently not a neighbor. It // answers ErrNotFound for an anchor that is not there, because with one anchor // there is nothing else to say. This role answers with the EDGE RECORDS // THEMSELVES, for MANY anchors, keyed by source, and it reports a missing // anchor per anchor rather than failing the call. Different answer shape, // different miss policy, different arity: folding them together would give one // role two of each, which is the accretion the governing rule exists to stop. // // IT IS ALSO NOT BlockingAnnotator. That role answers a DERIVED, best-effort // decoration — the open blockers and the parent of a page of issues — where // this one answers raw stored rows with no derivation and no policy. // // THE DIRECTION IS OUTGOING, and there is no parameter for it. The question // this role answers is "what does each of these depend on"; the inbound // direction is a different read against a different key (the batched // target-keyed mirror), it has its own de-duplication rule across the two // dependency tables, and no front door asks for it in bulk today. A role born // with a direction nothing sets would be a promise nothing checks — see // CountRequest's missing free-text field for the same decision. When something // needs the inbound bulk read it gets its own role, exactly as this one did. // // THE DEPENDENCY TREE IS NOT HERE EITHER, for the reason Relations gives: a // recursive walk has a depth, a cycle policy and a node shape of its own. // // Implementations never mutate caller-owned request values, snapshot the // request at method entry, and apply validation and normalization only to // attempt-local clones. EdgeReadRequest travels by value, so IDs and Types are // the members a body could otherwise write through to the caller: reading them // into a set is fine, sorting or de-duplicating them in place is not. // // Reading edges 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 EdgeReader interface { // ReadEdges returns each anchor's stored outgoing edges. // // The anchors' existence and their edges are read from ONE consistent view, // so an anchor cannot be reported missing by a probe that raced a create // the edge read then saw. That is the same promise Relations makes for its // single anchor, and it is the reason this is one method rather than a // caller's existence check followed by a caller's edge read. // // A request naming only anchors that are not there is a successful call // whose every entry reports Missing: there is no ErrNotFound on this role, // because a batch that failed for one absent id would throw away the // answers for the ids that were found. ReadEdges(ctx context.Context, req EdgeReadRequest) (EdgeReadResult, error) }