diff --git a/backend/conformance/batch_closer_contract.go b/backend/conformance/batch_closer_contract.go index ad6223576..539644c77 100644 --- a/backend/conformance/batch_closer_contract.go +++ b/backend/conformance/batch_closer_contract.go @@ -1158,6 +1158,64 @@ func assertBatchCloserCarriesNoPrecondition(t *testing.T) { } } +// RunBatchCloserSettlesTheDependersOfWhatItClosed pins the blocked-state +// clause the leaf states for this role: what LANDS leaves its dependers +// settled in the SAME transaction the batch commits. +// +// The existing claim case observes an unblocking from inside a batch only +// THROUGH THE CLAIM — a row the batch unblocked turns up as the winner. That +// is a role answer, and a role answer to "is this ready" can be computed from +// the live edge set by a backend that never denormalized. This one reads the +// raw column, which is the read that cannot be satisfied that way. +// +// The batch closes a blocker AND an unrelated item, so a body that collapsed +// the batch to its first item is still visibly wrong; the control depender +// hangs off a blocker the batch never names. +func RunBatchCloserSettlesTheDependersOfWhatItClosed(t *testing.T, ctx context.Context, fixture BatchCloserFixture) { + t.Helper() + blocker := fixture.IssuePrefix + "-bsbatch-blocker" + other := fixture.IssuePrefix + "-bsbatch-other" + depender := fixture.IssuePrefix + "-bsbatch-depender" + child := fixture.IssuePrefix + "-bsbatch-child" + wispDepender := fixture.IssuePrefix + "-bsbatch-wispdep" + controlBlocker := fixture.IssuePrefix + "-bsbatch-ctlblocker" + controlDepender := fixture.IssuePrefix + "-bsbatch-ctldepender" + for _, id := range []string{blocker, other, depender, child, controlBlocker, controlDepender} { + seedBatchCloserIssue(t, ctx, fixture, id) + } + seedBatchCloserWisp(t, ctx, fixture, wispDepender) + seedBatchCloserEdge(t, ctx, fixture, depender, blocker, types.DepBlocks) + seedBatchCloserEdge(t, ctx, fixture, child, depender, types.DepParentChild) + seedBatchCloserEdge(t, ctx, fixture, wispDepender, blocker, types.DepBlocks) + seedBatchCloserEdge(t, ctx, fixture, controlDepender, controlBlocker, types.DepBlocks) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requirePlaneResidency(t, blockedWisp(wispDepender)) + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the direct depender of a batch item") + probe.requireBlockedByOpenBlocker(t, blockedWisp(wispDepender), blockedIssue(blocker), "the cross-plane depender of a batch item") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), "the child's block is inherited from the depender") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlDepender), blockedIssue(controlBlocker), "the control's blocker is in no batch") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(depender), blockedIssue(child), blockedWisp(wispDepender)}, + []blockedStateRow{blockedIssue(controlDepender)}) + + result, err := fixture.Closer.CloseBatch(ctx, publicops.CloseBatchRequest{ + Actor: "closer", + Items: []publicops.BatchCloseItem{{IssueID: blocker}, {IssueID: other}}, + }) + if err != nil { + t.Fatalf("CloseBatch: %v", err) + } + for i, outcome := range result.Outcomes { + if outcome.Err != nil || !outcome.Changed { + t.Fatalf("outcome[%d] = %#v, want a landed close: the postcondition only applies to what LANDED", i, outcome) + } + } + + flip.requireFlippedTo(t, 0, "a batch settles the dependers of every item that landed, in the transaction the batch commits") +} + func seedBatchCloserIssue(t *testing.T, ctx context.Context, fixture BatchCloserFixture, id string, labels ...string) { t.Helper() issue := &types.Issue{ diff --git a/backend/conformance/blocked_state.go b/backend/conformance/blocked_state.go new file mode 100644 index 000000000..ed0de8607 --- /dev/null +++ b/backend/conformance/blocked_state.go @@ -0,0 +1,402 @@ +package conformance + +import ( + "context" + "fmt" + "testing" + + "github.com/steveyegge/beads/internal/types" +) + +// This file is the ONE assertion kit every is_blocked postcondition case in +// this package goes through, so five role contracts cannot drift into five +// slightly different versions of one promise. The promise itself is +// issueops.BlockedStateInvariant, cited BY SYMBOL from each case; nothing here +// asserts more than that anchor says. +// +// WHAT THE THREE LEGS ARE WORTH, per role, because it is not uniform and the +// mutation verdicts depend on it: +// +// - DependencyEditor is TWO GENUINE VOTES plus an engine check. The add and +// remove wirings are hand-mirrored between internal/storage/issueops +// (dependencies.go addDependencyInTx / removeDependencyInTx, shared by the +// two store backends) and internal/storage/domain/db (dependency.go Insert +// / Delete, the unit-of-work body). The second file's comment cites the +// first, which is exactly what a mirrored body looks like the day before it +// stops being one: bd-6dnrw.44 item 3 was a uow copy that skipped the +// descendant expansion. +// - Lifecycle.Update's status crossing is TWO GENUINE VOTES: issueops +// update.go and domain/db issue.go Update each decide independently when a +// status move counts as a crossing. +// - Deleter is TWO GENUINE VOTES: issueops delete.go against domain +// issue_delete.go. +// - Lifecycle.Close, Lifecycle.Reopen and BatchCloser are ONE BODY plus a +// wrapper and engine check. All three legs reach issueops.closeIssueInTx +// and ReopenIssueInTx, uow through the domain issue repository. Their cases +// still run everywhere, for the reason the TreeWalker contract gives — every +// measured drift in that family lived in a WRAPPER — but a mutation there +// reddens all three legs at once and proves nothing about per-leg wiring. +// +// TWO STRUCTURAL ASYMMETRIES, RECORDED HERE AND DELIBERATELY NOT FIXED. Both +// are shape differences between the store-backed and unit-of-work wirings that +// are not semantic divergences today; the cases pin the behavior so that if +// either becomes one, it becomes one loudly. +// +// - CREATE-WITH-EDGES runs ONE terminal recompute over the union of created +// ids and per-edge affected sets on the store-backed side +// (internal/storage/issueops/create.go), and per-edge maintenance through +// the dependency repository's Insert on the unit-of-work side. Convergent +// by ARGUMENT — adds are monotonic and the one non-monotonic add +// (parent-child) recomputes on both — and an argument is not a pinned fact. +// RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction +// is what pins it. +// - THE WISP PLANE has store-only recompute call sites with no unit-of-work +// twin: the persistence move (dolt's demoteToWispInTx) and the store's own +// wisp delete and batch wisp delete. Neither is on a role path — the +// Deleter role reaches wisps through the shared delete body, and a wisp +// CLOSE routes inside closeIssueInTx on all three legs rather than through +// a separate site — so no case here covers them, and that is a scope +// statement rather than an omission. +// +// HOW THESE CASES CANNOT BE THE DEFECT THIS PROGRAM ALREADY SHIPPED. One +// retired case seeded is_blocked = 1 with no blocker edge, so the guard it was +// named for short-circuited and it could never fail +// (engdocs/ADDING_AN_ISSUEOPS_ROLE.md, "Ask what the fixture makes +// unobservable"). Four structural rules, enforced here rather than asked for: +// +// 1. THE FIXTURE NEVER WRITES THE FLAG. There is no hook in this file that +// sets is_blocked, and none of the role fixtures has one. Every state is +// built through role verbs and the column value is EARNED, then read raw. +// 2. EVERY CASE FLIPS. blockedStateFlip refuses at t.Fatal if the pre-verb raw +// value already equals the value the case is about to assert, so a body +// that recomputes nothing fails by construction instead of passing on a +// value the seed happened to leave behind. +// 3. A BLOCKED PRECONDITION PINS THE REASON. requireBlockedByOpenBlocker +// checks the flag AND the edge AND the blocker's open status; +// requireBlockedWithNoDirectBlockerEdges checks the flag AND the absence of +// any direct edge, which is the pair the retired case lacked. +// 4. EVERY CASE CARRIES A CONTROL that must NOT move, read through the same +// raw reader, so a reader pointed at the wrong plane or a seed that never +// landed shows up as a green control that should have been a red one. +// +// Reads go through the fixture's QueryScalar hook rather than a fixture value, +// because the five role fixtures are five types with one identically-shaped +// hook; taking the hook is what lets one kit serve all of them. + +// blockedStatePlane names one of the two issue planes and the tables that hold +// its rows and its outgoing edges. Cross-plane cases assert residency rather +// than assuming it: cross-plane and cross-tier is where the earlier is_blocked +// defects lived (bd-6dnrw.44, and the reason dolt/crosstier_dep_test.go +// exists). +type blockedStatePlane struct { + name string + rows string + edges string +} + +var ( + blockedStateIssues = blockedStatePlane{name: "issue", rows: "issues", edges: "dependencies"} + blockedStateWisps = blockedStatePlane{name: "wisp", rows: "wisps", edges: "wisp_dependencies"} +) + +// blockedStateRow names one row by id and plane. Everything in this file takes +// one of these rather than a bare id, so a case can never read the issues table +// for a row that lives in the wisps one and conclude it is unblocked. +type blockedStateRow struct { + ID string + Plane blockedStatePlane +} + +func blockedIssue(id string) blockedStateRow { + return blockedStateRow{ID: id, Plane: blockedStateIssues} +} +func blockedWisp(id string) blockedStateRow { return blockedStateRow{ID: id, Plane: blockedStateWisps} } + +func (r blockedStateRow) String() string { return r.Plane.name + " " + r.ID } + +// blockedStateProbe is the raw reader. It reads COLUMNS, never role answers: +// is_blocked is derived AND persisted, so a case that asks a role whether an +// issue is blocked passes against a backend that never denormalizes, which is +// the whole failure mode these cases exist to catch. +type blockedStateProbe struct { + ctx context.Context + queryScalar func(context.Context, string, []any, ...any) error +} + +func newBlockedStateProbe(ctx context.Context, queryScalar func(context.Context, string, []any, ...any) error) *blockedStateProbe { + return &blockedStateProbe{ctx: ctx, queryScalar: queryScalar} +} + +// rawBlocked reads the stored flag. A missing row is a FAILURE, not a zero: a +// reader that decayed an absent row to "not blocked" would make every unmark +// assertion pass against a fixture whose seed never landed. +func (p *blockedStateProbe) rawBlocked(t *testing.T, row blockedStateRow) int { + t.Helper() + var blocked int + //nolint:gosec // G201: the table name comes from the two plane constants above. + query := fmt.Sprintf("SELECT CAST(COALESCE(is_blocked, 0) AS SIGNED) FROM %s WHERE id = ?", row.Plane.rows) + if err := p.queryScalar(p.ctx, query, []any{row.ID}, &blocked); err != nil { + t.Fatalf("read raw is_blocked for %s: %v", row, err) + } + return blocked +} + +// rawUpdatedAt reads the timestamp the non-perturbation clause of +// issueops.BlockedStateInvariant protects. It is read as text at column +// precision, which is the granularity a merge between two clones compares. +func (p *blockedStateProbe) rawUpdatedAt(t *testing.T, row blockedStateRow) string { + t.Helper() + var stamp string + //nolint:gosec // G201: the table name comes from the two plane constants above. + query := fmt.Sprintf("SELECT COALESCE(CAST(updated_at AS CHAR), '') FROM %s WHERE id = ?", row.Plane.rows) + if err := p.queryScalar(p.ctx, query, []any{row.ID}, &stamp); err != nil { + t.Fatalf("read raw updated_at for %s: %v", row, err) + } + return stamp +} + +func (p *blockedStateProbe) rawStatus(t *testing.T, row blockedStateRow) string { + t.Helper() + var status string + //nolint:gosec // G201: the table name comes from the two plane constants above. + query := fmt.Sprintf("SELECT status FROM %s WHERE id = ?", row.Plane.rows) + if err := p.queryScalar(p.ctx, query, []any{row.ID}, &status); err != nil { + t.Fatalf("read raw status for %s: %v", row, err) + } + return status +} + +// directBlockerEdges counts the outgoing edges that would make a row's block +// DIRECT rather than inherited. Both blocking types count, because the +// predicate treats them alike. +func (p *blockedStateProbe) directBlockerEdges(t *testing.T, row blockedStateRow) int { + t.Helper() + var edges int + //nolint:gosec // G201: the table name comes from the two plane constants above. + query := fmt.Sprintf("SELECT COUNT(*) FROM %s WHERE issue_id = ? AND (type = ? OR type = ?)", row.Plane.edges) + if err := p.queryScalar(p.ctx, query, []any{row.ID, string(types.DepBlocks), string(types.DepConditionalBlocks)}, &edges); err != nil { + t.Fatalf("count direct blocker edges for %s: %v", row, err) + } + return edges +} + +// requirePlaneResidency proves the row is where the case thinks it is: present +// in its own plane's table and ABSENT from the other. The second half is the +// half that catches a cross-plane routing regression, because a wisp that +// leaked a durable row would still read is_blocked correctly from one of them. +func (p *blockedStateProbe) requirePlaneResidency(t *testing.T, row blockedStateRow) { + t.Helper() + other := blockedStateIssues + if row.Plane.rows == blockedStateIssues.rows { + other = blockedStateWisps + } + for _, probe := range []struct { + table string + want int + }{{row.Plane.rows, 1}, {other.rows, 0}} { + var count int + //nolint:gosec // G201: the table name comes from the two plane constants above. + query := fmt.Sprintf("SELECT COUNT(*) FROM %s WHERE id = ?", probe.table) + if err := p.queryScalar(p.ctx, query, []any{row.ID}, &count); err != nil { + t.Fatalf("count %s rows named %s: %v", probe.table, row.ID, err) + } + if count != probe.want { + t.Fatalf("%s has %d row(s) in %s, want %d: the case is about plane residency and the seed did not produce it", + row, count, probe.table, probe.want) + } + } +} + +// requireBlockedByOpenBlocker pins a DIRECT blocked precondition together with +// its REASON — the flag, the edge, and the blocker's own open status. Asserting +// the flag alone is the shape of the retired defect: a row carrying 1 with no +// live blocker behind it means the case is testing a value nothing produced. +func (p *blockedStateProbe) requireBlockedByOpenBlocker(t *testing.T, row, blocker blockedStateRow, why string) { + t.Helper() + if got := p.rawBlocked(t, row); got != 1 { + t.Fatalf("%s raw is_blocked = %d, want 1 (%s)", row, got, why) + } + var edges int + //nolint:gosec // G201: the table names come from the two plane constants above. + query := fmt.Sprintf( + "SELECT COUNT(*) FROM %s WHERE issue_id = ? AND COALESCE(depends_on_issue_id, depends_on_wisp_id, depends_on_external) = ? AND (type = ? OR type = ?)", + row.Plane.edges) + if err := p.queryScalar(p.ctx, query, + []any{row.ID, blocker.ID, string(types.DepBlocks), string(types.DepConditionalBlocks)}, &edges); err != nil { + t.Fatalf("count the blocking edge %s -> %s: %v", row, blocker, err) + } + if edges != 1 { + t.Fatalf("%s carries %d blocking edges onto %s, want the 1 that makes its blocked state MEAN something (%s)", + row, edges, blocker, why) + } + if status := p.rawStatus(t, blocker); status == string(types.StatusClosed) || status == string(types.StatusPinned) { + t.Fatalf("blocker %s has status %q, which blocks nothing: the precondition is a LIVE blocker (%s)", blocker, status, why) + } +} + +// requireBlockedWithNoDirectBlockerEdges pins an INHERITED blocked +// precondition. The pair is the point: the flag says blocked, the edge count +// says the block cannot be its own, so what is under test is the transitive +// propagation and nothing else. This is the exact pair the retired +// fixture-defect case lacked. +func (p *blockedStateProbe) requireBlockedWithNoDirectBlockerEdges(t *testing.T, row blockedStateRow, why string) { + t.Helper() + if got := p.rawBlocked(t, row); got != 1 { + t.Fatalf("%s raw is_blocked = %d, want 1 (%s)", row, got, why) + } + if got := p.directBlockerEdges(t, row); got != 0 { + t.Fatalf("%s carries %d direct blocker edges, want 0: an inherited-block case that has its own blocker tests nothing (%s)", + row, got, why) + } +} + +func (p *blockedStateProbe) requireUnblocked(t *testing.T, row blockedStateRow, why string) { + t.Helper() + if got := p.rawBlocked(t, row); got != 0 { + t.Fatalf("%s raw is_blocked = %d, want 0 (%s)", row, got, why) + } +} + +// blockedStateFlip is the falsifiability harness. It snapshots the raw +// pre-verb value of every subject and every control, and requireFlippedTo then +// refuses to pass — or even to be a meaningful assertion — unless the subjects +// MOVED to the asserted value and the controls did not move at all. +type blockedStateFlip struct { + probe *blockedStateProbe + subjects []blockedStateRow + controls []blockedStateRow + blocked map[string]int + updatedAt map[string]string + written map[string]bool +} + +// watchFlip records the pre-verb state. Call it immediately before the verb +// under test; every row named here is read RAW. +// +// The controls are not decoration. A control is a row of the same shape whose +// cause the verb did not remove, so it proves the reader and the seed observe +// the database the subject assertion thinks they do — the pattern +// RunBatchCloserClaimNextSeesAnUnblockingFromItsOwnBatch already uses. +func (p *blockedStateProbe) watchFlip(t *testing.T, subjects, controls []blockedStateRow) *blockedStateFlip { + t.Helper() + if len(subjects) == 0 { + t.Fatal("watchFlip needs at least one subject row") + } + if len(controls) == 0 { + t.Fatal("watchFlip needs at least one control row: a case with nothing that must stay put cannot tell a correct recompute from a blanket one") + } + flip := &blockedStateFlip{ + probe: p, + subjects: subjects, + controls: controls, + blocked: make(map[string]int, len(subjects)+len(controls)), + updatedAt: make(map[string]string, len(subjects)+len(controls)), + written: make(map[string]bool, 1), + } + for _, row := range append(append([]blockedStateRow{}, subjects...), controls...) { + flip.blocked[row.String()] = p.rawBlocked(t, row) + flip.updatedAt[row.String()] = p.rawUpdatedAt(t, row) + } + return flip +} + +// watchControls records only rows that must NOT move, for the one case shape +// that has no flag of its own to flip: a verb the invariant says must not reach +// blocked state at all. Such a case still has to be falsifiable, and it is — +// but on a different column, so the case itself asserts a flip the verb DID +// make (a claimed row's status) and names that as its must-flip term. +func (p *blockedStateProbe) watchControls(t *testing.T, controls ...blockedStateRow) *blockedStateFlip { + t.Helper() + if len(controls) == 0 { + t.Fatal("watchControls needs at least one control row") + } + flip := &blockedStateFlip{ + probe: p, + controls: controls, + blocked: make(map[string]int, len(controls)), + updatedAt: make(map[string]string, len(controls)), + written: make(map[string]bool, 1), + } + for _, row := range controls { + flip.blocked[row.String()] = p.rawBlocked(t, row) + flip.updatedAt[row.String()] = p.rawUpdatedAt(t, row) + } + return flip +} + +// requireFlippedTo asserts the local-write clause of +// issueops.BlockedStateInvariant on the rows watchFlip snapshotted: +// +// - every subject NOW reads want, and DID NOT read want before. The second +// half is checked first and is fatal, because a subject that already held +// the asserted value makes the case unfalsifiable — it would pass against a +// backend whose verb did nothing at all. +// - every subject's updated_at is unchanged, which is the non-perturbation +// clause. It is asserted HERE, on rows that actually flipped, because the +// mark and unmark templates only touch a row whose value changes: a row +// that did not flip could not have had its timestamp bumped by a recompute, +// so asserting it there would be asserting nothing. A subject named to +// alsoWrites is exempt from THIS half and no other, because the verb writes +// that row for its own reasons. +// - every control still reads what it read, with its timestamp intact. +func (f *blockedStateFlip) requireFlippedTo(t *testing.T, want int, why string) { + t.Helper() + for _, row := range f.subjects { + key := row.String() + if f.blocked[key] == want { + t.Fatalf("%s already read is_blocked = %d before the verb ran, so this case cannot fail on the term it is named for (%s)", + row, want, why) + } + if got := f.probe.rawBlocked(t, row); got != want { + t.Errorf("%s raw is_blocked = %d after the verb, want %d — it read %d before (%s)", + row, got, want, f.blocked[key], why) + } + if f.written[key] { + continue + } + if got := f.probe.rawUpdatedAt(t, row); got != f.updatedAt[key] { + t.Errorf("%s updated_at moved %q -> %q across a blocked-state flip, want it untouched: a recompute is derived state, not a user edit (%s)", + row, f.updatedAt[key], got, why) + } + } + f.requireControlsUnmoved(t, why) +} + +// alsoWrites marks a row the verb under test LEGITIMATELY WRITES. Its blocked +// flag stays fully asserted either way — a control still must not move and a +// subject still must flip, because the invariant's non-perturbation clause is +// about the flag, and a claim must not change it. Only updated_at is waived, +// because the verb moves that row by design: a claim writes the row it claims, +// and a status crossing writes the row whose status crossed. +// +// Without this the case asserts the verb did not touch the row it exists to +// touch, and passes only when both writes land in the same second: updated_at +// is DATETIME with no fractional precision. That is the same second-precision +// property that made an updated_at comparison useless as a detector elsewhere +// in this suite, and here it produced a case that passed locally and failed in +// CI on a second boundary. +func (f *blockedStateFlip) alsoWrites(rows ...blockedStateRow) *blockedStateFlip { + for _, row := range rows { + f.written[row.String()] = true + } + return f +} + +// requireControlsUnmoved asserts only the control half, for the no-change cases +// that have no flip of their own to make. +func (f *blockedStateFlip) requireControlsUnmoved(t *testing.T, why string) { + t.Helper() + for _, row := range f.controls { + key := row.String() + if got := f.probe.rawBlocked(t, row); got != f.blocked[key] { + t.Errorf("control %s raw is_blocked moved %d -> %d, want it unchanged: the verb reached outside its affected set (%s)", + row, f.blocked[key], got, why) + } + if f.written[key] { + continue + } + if got := f.probe.rawUpdatedAt(t, row); got != f.updatedAt[key] { + t.Errorf("control %s updated_at moved %q -> %q, want it untouched (%s)", row, f.updatedAt[key], got, why) + } + } +} diff --git a/backend/conformance/deleter_contract.go b/backend/conformance/deleter_contract.go index 2584846f2..f44280a8d 100644 --- a/backend/conformance/deleter_contract.go +++ b/backend/conformance/deleter_contract.go @@ -681,6 +681,112 @@ func RunDeleterDoesNotMutateTheCallerRequest(t *testing.T, ctx context.Context, // --- fixture helpers ------------------------------------------------------- +// RunDeleterSettlesTheSurvivorsOfADeletedBlocker pins the blocked-state clause +// on the erasure verb: the rows it deletes are gone, so the promise is about +// the SURVIVORS. +// +// It is the same obligation the reference rewrite has, and it fails the same +// way when it is missed: an orphaned row left carrying is_blocked = 1 for a +// blocker that no longer exists is unblockable by any verb — nothing can close +// or remove the cause, because the cause is not there. Only a full repair +// clears it. +// +// The subjects cover all three arms the deletion's affected set has to walk: +// the direct depender, its parent-child descendant, and a WISP depender whose +// edge lives in the ephemeral table. +// +// Force is required rather than incidental: the dependers live outside the +// request, so an unforced delete is refused. That is the orphaning path +// exactly, which is the path where the flag would otherwise be stranded. +func RunDeleterSettlesTheSurvivorsOfADeletedBlocker(t *testing.T, ctx context.Context, fixture DeleterFixture) { + t.Helper() + blocker := deleterSeedIssue(t, ctx, fixture, "bsdel", "blocker") + depender := deleterSeedIssue(t, ctx, fixture, "bsdel", "depender") + child := deleterSeedIssue(t, ctx, fixture, "bsdel", "child") + wispDepender := deleterSeedWisp(t, ctx, fixture, "bsdel", "wispdep") + controlBlocker := deleterSeedIssue(t, ctx, fixture, "bsdel", "ctlblocker") + controlDepender := deleterSeedIssue(t, ctx, fixture, "bsdel", "ctldepender") + deleterAddEdge(t, ctx, fixture, depender, blocker) + deleterAddTypedEdge(t, ctx, fixture, child, depender, types.DepParentChild) + deleterAddEdge(t, ctx, fixture, wispDepender, blocker) + deleterAddEdge(t, ctx, fixture, controlDepender, controlBlocker) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requirePlaneResidency(t, blockedWisp(wispDepender)) + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the direct depender of the row about to be deleted") + probe.requireBlockedByOpenBlocker(t, blockedWisp(wispDepender), blockedIssue(blocker), "the cross-plane depender") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), "the child inherits and holds no blocker of its own") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlDepender), blockedIssue(controlBlocker), "the control's blocker is not deleted") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(depender), blockedIssue(child), blockedWisp(wispDepender)}, + []blockedStateRow{blockedIssue(controlDepender)}) + + result, err := fixture.Deleter.Delete(ctx, publicops.DeleteRequest{IDs: []string{blocker}, Force: true, Actor: "deleter"}) + if err != nil { + t.Fatalf("force-delete the blocker %s: %v", blocker, err) + } + if result.Deleted != 1 { + t.Fatalf("Deleted = %d, want the 1 named row", result.Deleted) + } + + flip.requireFlippedTo(t, 0, "a survivor whose only blocker was erased is left unblocked, and so is everything that inherited from it") +} + +// RunDeleterSettlesTheChildrenOfADeletedParent is the other arm of the same +// affected set, and it needs its own case because it is reached by a different +// query: the depender arm walks edges INTO the deleted row, this one walks the +// parent-child edges OUT of it to the children that inherited from it. +// +// The child survives the force-delete and its parent does not, so what is left +// is a row that was blocked only because of a row that no longer exists. +func RunDeleterSettlesTheChildrenOfADeletedParent(t *testing.T, ctx context.Context, fixture DeleterFixture) { + t.Helper() + blocker := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "blocker") + parent := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "parent") + child := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "child") + controlBlocker := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "ctlblocker") + controlParent := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "ctlparent") + controlChild := deleterSeedIssue(t, ctx, fixture, "bsdelpc", "ctlchild") + deleterAddEdge(t, ctx, fixture, parent, blocker) + deleterAddTypedEdge(t, ctx, fixture, child, parent, types.DepParentChild) + deleterAddEdge(t, ctx, fixture, controlParent, controlBlocker) + deleterAddTypedEdge(t, ctx, fixture, controlChild, controlParent, types.DepParentChild) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), "the child is blocked only through the parent about to be deleted") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(controlChild), "the control child's parent stays") + + flip := probe.watchFlip(t, []blockedStateRow{blockedIssue(child)}, []blockedStateRow{blockedIssue(controlChild)}) + + if _, err := fixture.Deleter.Delete(ctx, publicops.DeleteRequest{IDs: []string{parent}, Force: true, Actor: "deleter"}); err != nil { + t.Fatalf("force-delete the blocked parent %s: %v", parent, err) + } + var survives int + if err := fixture.QueryScalar(ctx, "SELECT COUNT(*) FROM issues WHERE id = ?", []any{child}, &survives); err != nil { + t.Fatalf("count the surviving child %s: %v", child, err) + } + if survives != 1 { + t.Fatalf("child %s has %d rows after a forced delete of its parent, want the orphaned survivor this case is about", child, survives) + } + + flip.requireFlippedTo(t, 0, "a child orphaned from a blocked parent inherits nothing, and the deleting transaction settles it") +} + +// deleterAddTypedEdge is deleterAddEdge for an edge that is not a block. The +// blocked-state cases need parent-child edges, which is the type that carries +// inheritance. +func deleterAddTypedEdge(t *testing.T, ctx context.Context, fixture DeleterFixture, source, target string, depType types.DependencyType) { + t.Helper() + if err := fixture.AddDependency(ctx, &types.Dependency{ + IssueID: source, + DependsOnID: target, + Type: depType, + }, "deleter-seed"); err != nil { + t.Fatalf("seeding %s edge %s -> %s: %v", depType, source, target, err) + } +} + func deleterIssue(fixture DeleterFixture, tag, name string, ephemeral bool) *types.Issue { return &types.Issue{ ID: fmt.Sprintf("%s-%s-%s", fixture.IssuePrefix, tag, name), diff --git a/backend/conformance/dependency_editor_contract.go b/backend/conformance/dependency_editor_contract.go index 4618c547d..3444888f8 100644 --- a/backend/conformance/dependency_editor_contract.go +++ b/backend/conformance/dependency_editor_contract.go @@ -42,8 +42,15 @@ type DependencyEditorFixture struct { // CreateWisp seeds an ephemeral issue in the wisps plane. It is a separate // field rather than an Ephemeral flag on CreateIssue because the three // adapters reach the two planes through different verbs. - CreateWisp func(context.Context, *types.Issue, string) error - QueryScalar func(context.Context, string, []any, ...any) error + CreateWisp func(context.Context, *types.Issue, string) error + // AddDependency seeds ONE edge out of band of the role, and is needed for + // exactly one thing the role's own request type cannot express: a + // DependencyEdge carries no metadata, so a waits-for edge with an + // any-children GATE on it can only be seeded through the kit's hook. The + // blocked-state case that needs one seeds only the precondition through it; + // the verb under test is still AddDependencies. + AddDependency func(context.Context, *types.Dependency, string) error + QueryScalar func(context.Context, string, []any, ...any) error // CountHistory reports how many history entries the fixture's branch has. // The cases that need it take it before and after the operation under test, // because two commits made inside one second tie on date and their relative @@ -1466,6 +1473,261 @@ func RunDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle(t *testing. assertDependencyEditorNoEdgesFrom(t, ctx, fixture, wispA) } +// RunDependencyEditorAddMarksItsSourceInTheSameVerb pins the local-write +// clause of issueops.BlockedStateInvariant on the add half of this role: an +// edge onto a LIVE target leaves the source's stored is_blocked settled inside +// the transaction that wrote the edge, and an edge onto a closed one leaves it +// alone. +// +// The two edges land in ONE request, so the twin differs from the subject in +// exactly one fact — the target's status — and nothing else. That is what makes +// the zero meaningful: the twin's edge is asserted present, so its 0 is a value +// the predicate produced rather than the absence of a seed. The retired +// is_blocked case failed on precisely that distinction. +// +// The subject read is RAW. Asking the role whether the source is blocked would +// pass against a backend that answered from the live edge set and never +// denormalized, which is the whole point of a derived-AND-persisted column. +func RunDependencyEditorAddMarksItsSourceInTheSameVerb(t *testing.T, ctx context.Context, fixture DependencyEditorFixture) { + t.Helper() + blocker := fixture.IssuePrefix + "-bsadd-blocker" + source := fixture.IssuePrefix + "-bsadd-source" + doneBlocker := fixture.IssuePrefix + "-bsadd-doneblocker" + twin := fixture.IssuePrefix + "-bsadd-twin" + control := fixture.IssuePrefix + "-bsadd-control" + for _, id := range []string{blocker, source, twin, control} { + seedDependencyEditorIssue(t, ctx, fixture, id) + } + seedDependencyEditorIssueAtStatus(t, ctx, fixture, doneBlocker, types.StatusClosed) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(source)}, + []blockedStateRow{blockedIssue(twin), blockedIssue(control)}) + + if _, err := fixture.Editor.AddDependencies(ctx, publicops.AddDependenciesRequest{ + Actor: "writer", + Edges: []publicops.DependencyEdge{ + {IssueID: source, DependsOnID: blocker, Type: publicops.DepBlocks}, + {IssueID: twin, DependsOnID: doneBlocker, Type: publicops.DepBlocks}, + }, + }); err != nil { + t.Fatalf("AddDependencies for the blocked-state add case: %v", err) + } + + flip.requireFlippedTo(t, 1, "a blocks edge onto a live target blocks its source, and BlockedStateInvariant settles it in the writing transaction") + probe.requireBlockedByOpenBlocker(t, blockedIssue(source), blockedIssue(blocker), + "the postcondition is the flag AND the reason behind it") + + // The twin's zero is only worth anything if its edge actually landed. + assertDependencyEdgeTypedCount(t, ctx, fixture, "dependencies", twin, doneBlocker, string(publicops.DepBlocks), 1) + if status := probe.rawStatus(t, blockedIssue(doneBlocker)); status != string(types.StatusClosed) { + t.Fatalf("twin's blocker %s has status %q, want %q: the twin differs from the subject in the target's status alone", + doneBlocker, status, types.StatusClosed) + } +} + +// RunDependencyEditorRemoveUnmarksItsSourceAndDescendants pins the remove half, +// and the part of the local-write clause that says the affected rows are not +// only the row the request names: removing the source's last blocking edge +// unblocks the source AND the parent-child descendant that inherited the block +// from it. +// +// THE DESCENDANT IS THE POINT. bd-6dnrw.44 item 3 was a unit-of-work body that +// computed the affected set without expanding by parent-child descendants, so +// the named row settled and its children stayed stale. A case that watched only +// the source would have passed against it. +// +// The child's precondition pins the flag AND zero direct blocker edges of its +// own, so the case cannot be satisfied by a child that was blocked for its own +// reasons — the pair the retired fixture-defect case lacked. +func RunDependencyEditorRemoveUnmarksItsSourceAndDescendants(t *testing.T, ctx context.Context, fixture DependencyEditorFixture) { + t.Helper() + blocker := fixture.IssuePrefix + "-bsrm-blocker" + parent := fixture.IssuePrefix + "-bsrm-parent" + child := fixture.IssuePrefix + "-bsrm-child" + controlBlocker := fixture.IssuePrefix + "-bsrm-ctlblocker" + controlParent := fixture.IssuePrefix + "-bsrm-ctlparent" + for _, id := range []string{blocker, parent, child, controlBlocker, controlParent} { + seedDependencyEditorIssue(t, ctx, fixture, id) + } + + if _, err := fixture.Editor.AddDependencies(ctx, publicops.AddDependenciesRequest{ + Actor: "writer", + Edges: []publicops.DependencyEdge{ + {IssueID: parent, DependsOnID: blocker, Type: publicops.DepBlocks}, + {IssueID: child, DependsOnID: parent, Type: publicops.DepParentChild}, + {IssueID: controlParent, DependsOnID: controlBlocker, Type: publicops.DepBlocks}, + }, + }); err != nil { + t.Fatalf("seed the blocked hierarchy through the role: %v", err) + } + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedByOpenBlocker(t, blockedIssue(parent), blockedIssue(blocker), "the parent holds the only cause in this hierarchy") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), "the child's block is INHERITED, which is what the removal has to reach") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlParent), blockedIssue(controlBlocker), "the control's cause is not the one being removed") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(parent), blockedIssue(child)}, + []blockedStateRow{blockedIssue(controlParent)}) + + removed, err := fixture.Editor.RemoveDependency(ctx, publicops.RemoveDependencyRequest{ + Actor: "writer", IssueID: parent, DependsOnID: blocker, + }) + if err != nil { + t.Fatalf("RemoveDependency %s -> %s: %v", parent, blocker, err) + } + if !removed.Removed { + t.Fatalf("RemoveDependency %s -> %s reported Removed = false, want the seeded edge", parent, blocker) + } + + flip.requireFlippedTo(t, 0, + "removing the last cause unblocks the source AND everything that inherited from it, per BlockedStateInvariant's local-write clause") +} + +// RunDependencyEditorMaintainsBlockedStateAcrossPlanes pins the clause that +// blocking crosses the two planes in BOTH directions, and that inheritance +// crosses them too. All four subjects settle inside one request. +// +// PLANE RESIDENCY IS ASSERTED, not assumed. Cross-plane and cross-tier is where +// the earlier is_blocked defects lived, and a wisp that leaked a durable row +// would still read a correct flag from one of the two tables — so each row is +// checked present in its own plane's table and ABSENT from the other before the +// flags mean anything. +// +// The wisp child is the sharpest of the four: its parent is a durable issue and +// its own edge lives in wisp_dependencies, so it is reached only by an affected +// set that expands across planes as well as down the hierarchy. +func RunDependencyEditorMaintainsBlockedStateAcrossPlanes(t *testing.T, ctx context.Context, fixture DependencyEditorFixture) { + t.Helper() + issueTarget := fixture.IssuePrefix + "-bsxp-issuetarget" + wispSource := fixture.IssuePrefix + "-bsxp-wispsource" + wispTarget := fixture.IssuePrefix + "-bsxp-wisptarget" + issueSource := fixture.IssuePrefix + "-bsxp-issuesource" + blockedParent := fixture.IssuePrefix + "-bsxp-parent" + wispChild := fixture.IssuePrefix + "-bsxp-wispchild" + freeIssue := fixture.IssuePrefix + "-bsxp-freeissue" + freeWisp := fixture.IssuePrefix + "-bsxp-freewisp" + for _, id := range []string{issueTarget, issueSource, blockedParent, freeIssue} { + seedDependencyEditorIssue(t, ctx, fixture, id) + } + for _, id := range []string{wispSource, wispTarget, wispChild, freeWisp} { + seedDependencyEditorWisp(t, ctx, fixture, id) + } + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + for _, row := range []blockedStateRow{ + blockedIssue(issueTarget), blockedIssue(issueSource), blockedIssue(blockedParent), blockedIssue(freeIssue), + blockedWisp(wispSource), blockedWisp(wispTarget), blockedWisp(wispChild), blockedWisp(freeWisp), + } { + probe.requirePlaneResidency(t, row) + } + + flip := probe.watchFlip(t, + []blockedStateRow{blockedWisp(wispSource), blockedIssue(issueSource), blockedIssue(blockedParent), blockedWisp(wispChild)}, + []blockedStateRow{blockedIssue(freeIssue), blockedWisp(freeWisp)}) + + if _, err := fixture.Editor.AddDependencies(ctx, publicops.AddDependenciesRequest{ + Actor: "writer", + Edges: []publicops.DependencyEdge{ + // wisp blocked by issue, and issue blocked by wisp: the two + // directions the invariant says are symmetric. + {IssueID: wispSource, DependsOnID: issueTarget, Type: publicops.DepBlocks}, + {IssueID: issueSource, DependsOnID: wispTarget, Type: publicops.DepBlocks}, + // A wisp child inheriting from a durable blocked parent. The + // parent-child edge is applied FIRST (the role applies hierarchy + // before blocking edges), so the child is only reachable through the + // affected set the later blocking edge expands. + {IssueID: wispChild, DependsOnID: blockedParent, Type: publicops.DepParentChild}, + {IssueID: blockedParent, DependsOnID: issueTarget, Type: publicops.DepBlocks}, + }, + }); err != nil { + t.Fatalf("AddDependencies across both planes: %v", err) + } + + flip.requireFlippedTo(t, 1, "blocking and inheritance cross the two planes in both directions") + probe.requireBlockedByOpenBlocker(t, blockedWisp(wispSource), blockedIssue(issueTarget), "a wisp is blocked by a live issue") + probe.requireBlockedByOpenBlocker(t, blockedIssue(issueSource), blockedWisp(wispTarget), "an issue is blocked by a live wisp") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedWisp(wispChild), + "the wisp child's block is inherited across the plane boundary, not its own") +} + +// RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate pins the ONE add +// that is not monotonic, and it is the case that tells MARK-ONLY wiring from +// RECOMPUTE wiring. +// +// Every other add can only ADD blockage, so both hand-mirrored bodies take a +// mark-only pass for it. A parent-child add cannot: an ALREADY-CLOSED child +// satisfies an any-children waits-for gate, so the waiter must come UNBLOCKED +// as a result of an add. Both bodies carve that case out to a full recompute +// and both say so in a comment; nothing pinned it at the role until now. Swap +// either carve-out back to the mark-only pass and this case is the one that +// goes red. +// +// The control is a second waiter on the SAME spawner under the default +// all-children gate. It is inside the affected set — the same recompute visits +// it — and it must stay blocked, so the case separates "the gate was +// re-evaluated" from "the flag was cleared". +func RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t *testing.T, ctx context.Context, fixture DependencyEditorFixture) { + t.Helper() + if fixture.AddDependency == nil { + t.Skip("fixture has no AddDependency hook: a waits-for GATE lives in edge metadata, which AddDependenciesRequest cannot carry") + } + spawner := fixture.IssuePrefix + "-bsgate-spawner" + openChild := fixture.IssuePrefix + "-bsgate-openchild" + closedChild := fixture.IssuePrefix + "-bsgate-closedchild" + waiterAny := fixture.IssuePrefix + "-bsgate-waiterany" + waiterAll := fixture.IssuePrefix + "-bsgate-waiterall" + for _, id := range []string{spawner, openChild, waiterAny, waiterAll} { + seedDependencyEditorIssue(t, ctx, fixture, id) + } + seedDependencyEditorIssueAtStatus(t, ctx, fixture, closedChild, types.StatusClosed) + + if _, err := fixture.Editor.AddDependencies(ctx, publicops.AddDependenciesRequest{ + Actor: "writer", + Edges: []publicops.DependencyEdge{{IssueID: openChild, DependsOnID: spawner, Type: publicops.DepParentChild}}, + }); err != nil { + t.Fatalf("seed the spawner's open child: %v", err) + } + for _, gate := range []struct { + waiter string + gate string + }{{waiterAny, types.WaitsForAnyChildren}, {waiterAll, types.WaitsForAllChildren}} { + edge, err := types.NewWaitsForDependency(gate.waiter, spawner, gate.gate) + if err != nil { + t.Fatalf("build the %s waits-for edge: %v", gate.gate, err) + } + if err := fixture.AddDependency(ctx, edge, "seed"); err != nil { + t.Fatalf("seed the %s waits-for edge %s -> %s: %v", gate.gate, gate.waiter, spawner, err) + } + } + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(waiterAny), "the any-children waiter is gated, not edge-blocked") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(waiterAll), "the all-children waiter is gated, not edge-blocked") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(waiterAny)}, + []blockedStateRow{blockedIssue(waiterAll)}) + + if _, err := fixture.Editor.AddDependencies(ctx, publicops.AddDependenciesRequest{ + Actor: "writer", + Edges: []publicops.DependencyEdge{{IssueID: closedChild, DependsOnID: spawner, Type: publicops.DepParentChild}}, + }); err != nil { + t.Fatalf("add the already-closed child: %v", err) + } + + flip.requireFlippedTo(t, 0, + "an already-closed child satisfies an any-children gate, so this ADD must UNBLOCK — the one add a mark-only pass cannot serve") + + // The all-children control is only a control if its own gate is still + // genuinely unsatisfied, which is the open child nobody touched. + if status := probe.rawStatus(t, blockedIssue(openChild)); status != string(types.StatusOpen) { + t.Fatalf("the spawner's open child %s has status %q, want %q: the all-children control depends on it", openChild, status, types.StatusOpen) + } +} + func seedDependencyEditorIssue(t *testing.T, ctx context.Context, fixture DependencyEditorFixture, id string) { t.Helper() if err := fixture.CreateIssue(ctx, dependencyEditorSeed(id, false), "seed"); err != nil { @@ -1473,6 +1735,19 @@ func seedDependencyEditorIssue(t *testing.T, ctx context.Context, fixture Depend } } +// seedDependencyEditorIssueAtStatus seeds a durable issue that is already in a +// terminal status. It seeds a STATUS, never the is_blocked column: no fixture +// in this package can write that flag, so every value a case reads was earned +// by a role verb. +func seedDependencyEditorIssueAtStatus(t *testing.T, ctx context.Context, fixture DependencyEditorFixture, id string, status types.Status) { + t.Helper() + seed := dependencyEditorSeed(id, false) + seed.Status = status + if err := fixture.CreateIssue(ctx, seed, "seed"); err != nil { + t.Fatalf("seed issue %s at status %q: %v", id, status, err) + } +} + func seedDependencyEditorWisp(t *testing.T, ctx context.Context, fixture DependencyEditorFixture, id string) { t.Helper() if err := fixture.CreateWisp(ctx, dependencyEditorSeed(id, true), "seed"); err != nil { diff --git a/backend/conformance/issue_operations_contract.go b/backend/conformance/issue_operations_contract.go index 29f8e2f17..46513418f 100644 --- a/backend/conformance/issue_operations_contract.go +++ b/backend/conformance/issue_operations_contract.go @@ -2645,6 +2645,208 @@ func readIssueOperationsRowMarks(t *testing.T, ctx context.Context, fixture Issu return marks } +// RunIssueOperationsUpdateStatusCrossingSettlesDependers pins the local-write +// clause of issueops.BlockedStateInvariant on Update, and it is the case with +// the most to say about per-backend WIRING in this file: the decision that a +// status move counts as a crossing is written TWICE, in +// internal/storage/issueops/update.go and in internal/storage/domain/db's +// issue Update, so the three legs are two genuine votes here. +// +// The crossing is open -> pinned and back, deliberately not open -> closed: +// pinned is a status Lifecycle.Close cannot produce, so this branch is +// reachable only through Update. Both directions run, because the mark and the +// unmark are separate SQL and a case that watches one exercises one. +// +// The depender is CREATED with its edge rather than seeded with one, which is +// why the fixture needs no dependency hook: the edge and the flag both come +// from role verbs, and no fixture in this package can write the flag at all. +func RunIssueOperationsUpdateStatusCrossingSettlesDependers(t *testing.T, ctx context.Context, fixture IssueOperationsStagingFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bsupd-blocker" + depender := fixture.IssuePrefix + "-bsupd-depender" + controlBlocker := fixture.IssuePrefix + "-bsupd-ctlblocker" + controlDepender := fixture.IssuePrefix + "-bsupd-ctldepender" + seedIssueOperationsLabeledIssue(t, ctx, fixture, blocker) + seedIssueOperationsLabeledIssue(t, ctx, fixture, controlBlocker) + createIssueOperationsBlockedIssue(t, ctx, fixture, depender, blocker) + createIssueOperationsBlockedIssue(t, ctx, fixture, controlDepender, controlBlocker) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the create carried the edge and earned the flag") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlDepender), blockedIssue(controlBlocker), "the control's blocker never moves") + + out := probe.watchFlip(t, []blockedStateRow{blockedIssue(depender)}, []blockedStateRow{blockedIssue(controlDepender)}) + if _, err := fixture.Operations.Update(ctx, publicops.UpdateRequest{ + Actor: "writer", IssueID: blocker, + Patch: publicops.IssuePatch{Status: publicops.Field[publicops.Status]{Set: true, Value: types.StatusPinned}}, + }); err != nil { + t.Fatalf("update %s to pinned: %v", blocker, err) + } + out.requireFlippedTo(t, 0, "pinning a blocker takes it out of the active set, so its depender is no longer blocked") + + back := probe.watchFlip(t, []blockedStateRow{blockedIssue(depender)}, []blockedStateRow{blockedIssue(controlDepender)}) + if _, err := fixture.Operations.Update(ctx, publicops.UpdateRequest{ + Actor: "writer", IssueID: blocker, + Patch: publicops.IssuePatch{Status: publicops.Field[publicops.Status]{Set: true, Value: types.StatusOpen}}, + }); err != nil { + t.Fatalf("update %s back to open: %v", blocker, err) + } + back.requireFlippedTo(t, 1, "unpinning the blocker returns it to the active set and re-blocks its depender") + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the postcondition is the flag AND the live blocker behind it") +} + +// RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction pins +// the create half, and with it the one structural asymmetry between the two +// bodies: the store-backed create runs ONE terminal recompute over the union of +// the created ids and every edge's affected set, while the unit-of-work create +// maintains blocked state per edge as its dependency repository writes them. +// The two are convergent by argument — adds are monotonic, and the one +// non-monotonic add recomputes on both sides — but an argument is not a pinned +// fact, and this is where a divergence would show. +// +// THE EXISTING ROW IS THE FALSIFIABLE TERM. A created row has no pre-value, so +// a case that only read the new row's flag could not tell "the create marked +// it" from "the column defaults that way". The reverse edge points an existing, +// already-read row at the new one, so the create must flip a row it did not +// create. +// +// The child is the transitive half, asserted with zero direct blocker edges of +// its own: creating a child of a blocked parent must leave it blocked in the +// creating transaction, not at the next recompute. +func RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t *testing.T, ctx context.Context, fixture IssueOperationsStagingFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bscreate-blocker" + waiting := fixture.IssuePrefix + "-bscreate-waiting" + free := fixture.IssuePrefix + "-bscreate-free" + created := fixture.IssuePrefix + "-bscreate-new" + for _, id := range []string{blocker, waiting, free} { + seedIssueOperationsLabeledIssue(t, ctx, fixture, id) + } + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireUnblocked(t, blockedIssue(waiting), "the existing row is clean until the create points it at the new one") + + flip := probe.watchFlip(t, []blockedStateRow{blockedIssue(waiting)}, []blockedStateRow{blockedIssue(free)}) + result, err := fixture.Operations.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{ + ID: created, Title: created, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask, + }, + Dependencies: []publicops.CreateDependency{ + // The new issue is blocked by an existing one... + {TargetID: blocker, Type: types.DepBlocks}, + // ...and an existing one is blocked by the new issue. + {TargetID: waiting, Type: types.DepBlocks, Reverse: true}, + }, + }) + if err != nil { + t.Fatalf("create %s with edges in both directions: %v", created, err) + } + if result.Issue == nil || result.Issue.ID != created { + t.Fatalf("create result = %#v, want the issue at %s", result.Issue, created) + } + + flip.requireFlippedTo(t, 1, "a reverse edge created with an issue blocks the row it points at, inside the creating transaction") + probe.requireBlockedByOpenBlocker(t, blockedIssue(created), blockedIssue(blocker), + "the created row settled against its own forward edge in the same transaction") + + // The transitive half: a child created under the blocked new row inherits + // the block with no blocker of its own. + child, err := fixture.Operations.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{Title: "child of a blocked parent", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask}, + ParentID: created, + }) + if err != nil { + t.Fatalf("create a child under the blocked %s: %v", created, err) + } + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child.Issue.ID), + "a child created under a blocked parent inherits the block in its own creating transaction") + probe.requireUnblocked(t, blockedIssue(free), "the control never entered any affected set") +} + +// RunIssueOperationsClaimLeavesBlockedStateAlone pins the last clause of +// issueops.BlockedStateInvariant: settling never reaches outside the affected +// set, so an unrelated blocked row is still blocked — for the same reason — +// after a neighboring claim. +// +// It is the only case in this family with no flag of its own to flip, so its +// falsifiable term is the STATUS the claim really moved: if the claim did not +// land, the case fails before it asserts anything about blocked state. The +// claimed row carries a `related` edge onto an open issue, which is the shape a +// predicate that counted every edge type would mark — so this case is red +// against that mutation and no other case is. +// +// It extends internal/storage/domain/db's ClaimDoesNotChangeIsBlocked, which +// runs on the unit-of-work leg alone, to all three, and adds the updated_at +// half. +func RunIssueOperationsClaimLeavesBlockedStateAlone(t *testing.T, ctx context.Context, fixture IssueOperationsStagingFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bsclaim-blocker" + blocked := fixture.IssuePrefix + "-bsclaim-blocked" + neighbor := fixture.IssuePrefix + "-bsclaim-neighbor" + claimed := fixture.IssuePrefix + "-bsclaim-claimed" + seedIssueOperationsLabeledIssue(t, ctx, fixture, blocker) + seedIssueOperationsLabeledIssue(t, ctx, fixture, neighbor) + createIssueOperationsBlockedIssue(t, ctx, fixture, blocked, blocker) + if _, err := fixture.Operations.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{ + ID: claimed, Title: claimed, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask, + }, + Dependencies: []publicops.CreateDependency{{TargetID: neighbor, Type: types.DepRelated}}, + }); err != nil { + t.Fatalf("create the claim target %s with a non-blocking edge: %v", claimed, err) + } + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedByOpenBlocker(t, blockedIssue(blocked), blockedIssue(blocker), "the bystander is blocked for a reason the claim does not touch") + probe.requireUnblocked(t, blockedIssue(claimed), "a related edge onto an open issue is not a block") + + // claimed is a FLAG control, not an updated_at control: the claim writes that + // row on purpose. + unmoved := probe.watchControls(t, blockedIssue(blocked), blockedIssue(claimed), blockedIssue(neighbor)). + alsoWrites(blockedIssue(claimed)) + updated, err := fixture.Operations.Update(ctx, publicops.UpdateRequest{Actor: "claimer", IssueID: claimed, Claim: true}) + if err != nil { + t.Fatalf("claim %s: %v", claimed, err) + } + // The must-flip term: without a landed claim this case asserts nothing. + if !updated.Changed || updated.Issue.Status != types.StatusInProgress { + t.Fatalf("claim of %s = (Changed %v, status %q), want a committed move to %q", + claimed, updated.Changed, updated.Issue.Status, types.StatusInProgress) + } + if got := probe.rawStatus(t, blockedIssue(claimed)); got != string(types.StatusInProgress) { + t.Fatalf("stored status for %s = %q, want %q: the claim has to have landed for the rest of this case to mean anything", + claimed, got, types.StatusInProgress) + } + + unmoved.requireControlsUnmoved(t, "a claim is not a blocked-state event and reaches nothing outside its own row") +} + +// createIssueOperationsBlockedIssue creates one open task blocked by an +// existing issue, through the role's own create-with-edges. The flag it ends up +// carrying is EARNED by that verb; nothing in these fixtures can write it. +func createIssueOperationsBlockedIssue(t *testing.T, ctx context.Context, fixture IssueOperationsStagingFixture, id, blockerID string) { + t.Helper() + if _, err := fixture.Operations.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{ + ID: id, Title: id, Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask, + }, + Dependencies: []publicops.CreateDependency{{TargetID: blockerID, Type: types.DepBlocks}}, + }); err != nil { + t.Fatalf("create %s blocked by %s: %v", id, blockerID, err) + } +} + // seedIssueOperationsLabeledIssue creates one open task at an explicit ID // carrying labels, through the store seed hook rather than the guarded create, // so the labels are already durable state when the case under test runs. diff --git a/backend/conformance/lifecycle_close_reopen_contract.go b/backend/conformance/lifecycle_close_reopen_contract.go index ada543620..12d82accc 100644 --- a/backend/conformance/lifecycle_close_reopen_contract.go +++ b/backend/conformance/lifecycle_close_reopen_contract.go @@ -382,11 +382,15 @@ func RunLifecycleCloseAdmitsAStaleBlockFlagWhoseBlockersHaveClosed(t *testing.T, // is not on that list, so a re-close that met one would be a refusal the // contract does not permit. // -// The state is reachable and not exotic: a forced close leaves the row closed -// with its blocker still open and its is_blocked column still set, because the -// recompute a close runs covers the rows whose blockedness the close CHANGED, -// not the closed row itself. Re-running the guard there makes every forced -// close of a blocked issue permanently un-re-closable. +// The state is reachable but NOT from a forced close alone, which is why the +// body below restores the column by hand. A close settles the row it closes: +// the closed row is in its own affected set and a closed row is never blocked, +// so the flag comes down with the status +// (RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild pins exactly that). +// What leaves a CLOSED row reading blocked is the invariant's merge clause — a +// pull that merges a forced close against a clone that still reads the row as +// blocked — and re-running the guard there would make that row permanently +// un-re-closable. // // RunLifecycleCloseIsIdempotentAndKeepsTheFirstClose does not cover it: its row // has no blocker, so `blocked` is false and the guard cannot fire whether or @@ -1172,6 +1176,228 @@ func RunLifecycleReopenProvenanceLabelsHistory(t *testing.T, ctx context.Context // forbids. The case seeds through the fixture kit's CreateWisp hook the day the // clause exists. +// RunLifecycleCloseSettlesItsTransitiveAndCrossPlaneDependers pins the +// local-write clause of issueops.BlockedStateInvariant on Close, which the +// existing cases in this file only ever read as a PRECONDITION. +// +// Close is where the affected set is widest, and the three subjects are the +// three ways it widens: the direct depender, that depender's parent-child child +// (which inherits and carries no blocker of its own), and a WISP depender whose +// edge lives in the ephemeral dependency table. A body that settled only the +// row the request named would pass a case watching the depender alone. +// +// Every subject's updated_at is asserted unchanged across the flip, which is +// the non-perturbation clause and can only be observed on a row that actually +// flipped: the mark and unmark templates never touch a row whose value stays +// put. +// +// WHAT IT DOES NOT COVER is the row the request names. Every subject here is +// downstream of the blocker and the blocker is itself unblocked, so the +// crossing row's own seat in the affected set belongs to +// RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild. +// +// UNLIKE the two-body cases on DependencyEditor and Deleter, all three legs +// reach ONE body here (internal/storage/issueops.closeIssueInTx; the +// unit-of-work leg through its domain issue repository). This case is a +// wrapper and engine check, not a third vote, and blocked_state.go's header +// says so. +func RunLifecycleCloseSettlesItsTransitiveAndCrossPlaneDependers(t *testing.T, ctx context.Context, fixture LifecycleCloseReopenFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bsclose-blocker" + depender := fixture.IssuePrefix + "-bsclose-depender" + child := fixture.IssuePrefix + "-bsclose-child" + wispDepender := fixture.IssuePrefix + "-bsclose-wispdep" + controlBlocker := fixture.IssuePrefix + "-bsclose-ctlblocker" + controlDepender := fixture.IssuePrefix + "-bsclose-ctldepender" + for _, id := range []string{blocker, depender, child, controlBlocker, controlDepender} { + lifecycleCloseReopenSeedIssue(t, ctx, fixture, id, types.StatusOpen, nil) + } + lifecycleCloseReopenSeedWisp(t, ctx, fixture, wispDepender) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, depender, blocker, types.DepBlocks) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, child, depender, types.DepParentChild) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, wispDepender, blocker, types.DepBlocks) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, controlDepender, controlBlocker, types.DepBlocks) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requirePlaneResidency(t, blockedWisp(wispDepender)) + probe.requirePlaneResidency(t, blockedIssue(blocker)) + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the direct depender") + probe.requireBlockedByOpenBlocker(t, blockedWisp(wispDepender), blockedIssue(blocker), "the cross-plane depender") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), "the child inherits its block and has none of its own") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlDepender), blockedIssue(controlBlocker), "the control's blocker is not the one being closed") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(depender), blockedIssue(child), blockedWisp(wispDepender)}, + []blockedStateRow{blockedIssue(controlDepender)}) + + closed, err := fixture.Lifecycle.Close(ctx, publicops.CloseRequest{Actor: "writer", IssueID: blocker}) + if err != nil { + t.Fatalf("close the blocker %s: %v", blocker, err) + } + if !closed.Changed { + t.Fatalf("close of %s reported Changed = false, want a committed close", blocker) + } + + flip.requireFlippedTo(t, 0, + "closing a blocker settles its dependers, their descendants and both planes before the close commits") +} + +// RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild pins the clause of +// issueops.BlockedStateInvariant that every other is_blocked case in this +// package reads only from the far side: A ROW THAT IS CLOSED OR PINNED IS NEVER +// BLOCKED. +// +// The sibling case above, the reopen case below and the Update crossing case +// all arrange for the row whose status moves to be UNBLOCKED itself, and watch +// something downstream of it. That leaves the crossing row's OWN seat in the +// affected set unpinned — internal/storage/issueops/blocked_state.go's +// AffectedByStatusChangeInTx seeds the set with the id whose status changed, +// and deleting that seed leaves every one of those cases green. What it strands +// is not a transient: a blocked row that keeps is_blocked = 1 after it closes +// is an ORPHANED FLAG, because nothing downstream of a closed row will ever +// change its blockedness again and no verb will recompute it. The merge clause +// is the only place the invariant admits a stale column, and this is not a +// merge. +// +// THE CHILD IS THE OTHER HALF OF THE SAME SEED. The affected set expands by +// parent-child descendants FROM ITS SEEDS, and the depender load that reaches a +// neighbor follows blocks and conditional-blocks edges only — never +// parent-child. Drop the crossing row from the seed and its children go with +// it, silently, because no other case in this file hangs a child off the row +// being closed: the sibling's child hangs off the DEPENDER. +// +// WHY THE CLOSE IS FORCED. Both unforced refusals stand in the way here, and +// for opposite reasons — the subject is blocked (ErrCloseBlocked) and it has an +// open child (CloseOpenChildrenError). The child-shaped block that +// RunLifecycleCloseAdmitsATransitivelyBlockedTarget uses clears the first and +// not the second, and closing the child to clear the second would take the +// second subject with it, since a closed row cannot be blocked and so has +// nothing left to flip. Force waives close policy and nothing else — +// CloseRequest.Force "bypasses only blocker and open-child close policy" and +// "never bypasses validation, ExpectedVersion, or lifecycle rules" +// (issueops/issueops.go:310-311) — so it is the shape that keeps both subjects +// observable, and it is not exotic: it is the same forced close of a +// blocked issue that RunLifecycleCloseIsIdempotentOnAClosedRowThatStillLooksBlocked +// is built on. +// +// All three legs reach ONE body here (internal/storage/issueops.closeIssueInTx), +// so this is a wrapper and engine check rather than a third vote, exactly as +// blocked_state.go's header says of the whole Close family. +func RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild(t *testing.T, ctx context.Context, fixture LifecycleCloseReopenFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bsself-blocker" + subject := fixture.IssuePrefix + "-bsself-subject" + child := fixture.IssuePrefix + "-bsself-child" + controlBlocker := fixture.IssuePrefix + "-bsself-ctlblocker" + controlDepender := fixture.IssuePrefix + "-bsself-ctldepender" + for _, id := range []string{blocker, subject, child, controlBlocker, controlDepender} { + lifecycleCloseReopenSeedIssue(t, ctx, fixture, id, types.StatusOpen, nil) + } + lifecycleCloseReopenSeedEdge(t, ctx, fixture, subject, blocker, types.DepBlocks) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, child, subject, types.DepParentChild) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, controlDepender, controlBlocker, types.DepBlocks) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requireBlockedByOpenBlocker(t, blockedIssue(subject), blockedIssue(blocker), + "the row whose status is about to cross is itself blocked, and by a live edge rather than a seeded column") + probe.requireBlockedWithNoDirectBlockerEdges(t, blockedIssue(child), + "the closed row's own child inherits the block and carries none of its own") + probe.requireBlockedByOpenBlocker(t, blockedIssue(controlDepender), blockedIssue(controlBlocker), + "the control is blocked for a reason this close never reaches") + + // The subject is a flag SUBJECT and an updated_at exemption: the close + // writes that row on purpose. The child is neither, so the non-perturbation + // clause is observed on it. + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(subject), blockedIssue(child)}, + []blockedStateRow{blockedIssue(controlDepender)}). + alsoWrites(blockedIssue(subject)) + + closed, err := fixture.Lifecycle.Close(ctx, publicops.CloseRequest{ + Actor: "writer", IssueID: subject, Reason: "shipped anyway", Force: true, + }) + if err != nil { + t.Fatalf("forced close of blocked %s with an open child: %v", subject, err) + } + if !closed.Changed || closed.Issue.Status != types.StatusClosed { + t.Fatalf("forced close of %s = %#v, want a committed close", subject, closed) + } + // The count is read for the FIXTURE, not for the policy: a child that was + // already closed could not be blocked, and the second subject would be a row + // with nothing to flip. + if closed.OpenChildren != 1 { + t.Fatalf("forced close of %s reports %d open children, want the 1 this case hung off it", subject, closed.OpenChildren) + } + if got := probe.rawStatus(t, blockedIssue(subject)); got != string(types.StatusClosed) { + t.Fatalf("stored status for %s = %q, want %q: the rest of this case is about what a CLOSED status means for the flag", + subject, got, types.StatusClosed) + } + // The blocker is still open, which is what makes the two flips below + // attributable to the SUBJECT closing rather than to its cause going away — + // the mechanism the sibling case already covers. + if got := probe.rawStatus(t, blockedIssue(blocker)); got != string(types.StatusOpen) { + t.Fatalf("blocker %s status = %q, want it still open", blocker, got) + } + + flip.requireFlippedTo(t, 0, + "a closed row is never blocked, and settling it settles its own parent-child child with it") +} + +// RunLifecycleReopenReblocksItsDependers is the other direction, and it is what +// makes the pair complete: the unmark template and the mark template are +// separate SQL, so a case that only ever watches a flag fall exercises one of +// them. +// +// The control is a depender whose blocker was CLOSED WHEN IT WAS SEEDED and +// never reopened. It has the same shape as the subject and the same zero, so it +// separates "reopening the blocker re-blocked this row" from "the verb re-marks +// whatever it can reach". +func RunLifecycleReopenReblocksItsDependers(t *testing.T, ctx context.Context, fixture LifecycleCloseReopenFixture) { + t.Helper() + + blocker := fixture.IssuePrefix + "-bsreopen-blocker" + depender := fixture.IssuePrefix + "-bsreopen-depender" + wispDepender := fixture.IssuePrefix + "-bsreopen-wispdep" + controlBlocker := fixture.IssuePrefix + "-bsreopen-ctlblocker" + controlDepender := fixture.IssuePrefix + "-bsreopen-ctldepender" + for _, id := range []string{blocker, depender, controlDepender} { + lifecycleCloseReopenSeedIssue(t, ctx, fixture, id, types.StatusOpen, nil) + } + lifecycleCloseReopenSeedIssue(t, ctx, fixture, controlBlocker, types.StatusClosed, nil) + lifecycleCloseReopenSeedWisp(t, ctx, fixture, wispDepender) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, depender, blocker, types.DepBlocks) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, wispDepender, blocker, types.DepBlocks) + lifecycleCloseReopenSeedEdge(t, ctx, fixture, controlDepender, controlBlocker, types.DepBlocks) + + probe := newBlockedStateProbe(ctx, fixture.QueryScalar) + probe.requirePlaneResidency(t, blockedWisp(wispDepender)) + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the pre-close state this case unwinds and rewinds") + probe.requireUnblocked(t, blockedIssue(controlDepender), "the control's blocker was already closed when its edge landed") + + if _, err := fixture.Lifecycle.Close(ctx, publicops.CloseRequest{Actor: "writer", IssueID: blocker}); err != nil { + t.Fatalf("close the blocker %s to reach the reopen precondition: %v", blocker, err) + } + probe.requireUnblocked(t, blockedIssue(depender), "the close is what put the subject at 0 — earned, never seeded") + probe.requireUnblocked(t, blockedWisp(wispDepender), "the cross-plane depender came down with it") + + flip := probe.watchFlip(t, + []blockedStateRow{blockedIssue(depender), blockedWisp(wispDepender)}, + []blockedStateRow{blockedIssue(controlDepender)}) + + reopened, err := fixture.Lifecycle.Reopen(ctx, publicops.ReopenRequest{Actor: "writer", IssueID: blocker}) + if err != nil { + t.Fatalf("reopen the blocker %s: %v", blocker, err) + } + if !reopened.Changed { + t.Fatalf("reopen of closed %s reported Changed = false, want a committed reopen", blocker) + } + + flip.requireFlippedTo(t, 1, "a reopened blocker blocks again, on both planes, before the reopen commits") + probe.requireBlockedByOpenBlocker(t, blockedIssue(depender), blockedIssue(blocker), "the postcondition is the flag AND the live blocker behind it") +} + // lifecycleCloseReopenCountHistory counts version-control entries carrying an // EXACT message, which is the only way to tell the caller's spelling from the // implementation's default. It is read as a delta by every caller: these diff --git a/internal/storage/dolt/batch_closer_contract_test.go b/internal/storage/dolt/batch_closer_contract_test.go index 08b04f6cd..16dabe654 100644 --- a/internal/storage/dolt/batch_closer_contract_test.go +++ b/internal/storage/dolt/batch_closer_contract_test.go @@ -125,6 +125,12 @@ func TestBatchCloserDoesNotMutateTheCallerRequest(t *testing.T) { conformance.RunBatchCloserDoesNotMutateTheCallerRequest(t, ctx, fixture) } +func TestBatchCloserSettlesTheDependersOfWhatItClosed(t *testing.T) { + fixture, ctx, cleanup := newDoltBatchCloserFixture(t, "bcblocked") + defer cleanup() + conformance.RunBatchCloserSettlesTheDependersOfWhatItClosed(t, ctx, fixture) +} + func newDoltBatchCloserFixture(t *testing.T, prefix string) (conformance.BatchCloserFixture, context.Context, func()) { t.Helper() store, storeCleanup := setupTestStore(t) diff --git a/internal/storage/dolt/deleter_contract_test.go b/internal/storage/dolt/deleter_contract_test.go index a71e9d17f..1c3b74424 100644 --- a/internal/storage/dolt/deleter_contract_test.go +++ b/internal/storage/dolt/deleter_contract_test.go @@ -69,6 +69,12 @@ func TestDeleterContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunDeleterDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("SettlesTheSurvivorsOfADeletedBlocker", func(t *testing.T) { + conformance.RunDeleterSettlesTheSurvivorsOfADeletedBlocker(t, ctx, fixture) + }) + t.Run("SettlesTheChildrenOfADeletedParent", func(t *testing.T) { + conformance.RunDeleterSettlesTheChildrenOfADeletedParent(t, ctx, fixture) + }) } // newDoltDeleterFixture composes the frozen role kit with this backend's diff --git a/internal/storage/dolt/dependency_editor_contract_test.go b/internal/storage/dolt/dependency_editor_contract_test.go index d74d95953..1b4fa8be8 100644 --- a/internal/storage/dolt/dependency_editor_contract_test.go +++ b/internal/storage/dolt/dependency_editor_contract_test.go @@ -193,6 +193,30 @@ func TestDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle(t *testing conformance.RunDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle(t, ctx, fixture) } +func TestDependencyEditorAddMarksItsSourceInTheSameVerb(t *testing.T) { + fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "bsadd") + defer cleanup() + conformance.RunDependencyEditorAddMarksItsSourceInTheSameVerb(t, ctx, fixture) +} + +func TestDependencyEditorRemoveUnmarksItsSourceAndDescendants(t *testing.T) { + fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "bsrm") + defer cleanup() + conformance.RunDependencyEditorRemoveUnmarksItsSourceAndDescendants(t, ctx, fixture) +} + +func TestDependencyEditorMaintainsBlockedStateAcrossPlanes(t *testing.T) { + fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "bsxp") + defer cleanup() + conformance.RunDependencyEditorMaintainsBlockedStateAcrossPlanes(t, ctx, fixture) +} + +func TestDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t *testing.T) { + fixture, ctx, cleanup := newDoltDependencyEditorFixture(t, "bsgate") + defer cleanup() + conformance.RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t, ctx, fixture) +} + // newDoltDependencyEditorFixture composes the backend's role fixture kit with // the accessor under test. Every hook but the accessor comes from the kit, so // the seeding and scalar-query plumbing stays identical to the other roles'. @@ -208,12 +232,13 @@ func newDoltDependencyEditorFixture(t *testing.T, prefix string) (conformance.De } kit := newDoltRoleFixtureKit(store, prefix) fixture := conformance.DependencyEditorFixture{ - IssuePrefix: kit.IssuePrefix, - Editor: editor, - CreateIssue: kit.CreateIssue, - CreateWisp: kit.CreateWisp, - QueryScalar: kit.QueryScalar, - CountHistory: kit.CountHistory, + IssuePrefix: kit.IssuePrefix, + Editor: editor, + CreateIssue: kit.CreateIssue, + CreateWisp: kit.CreateWisp, + AddDependency: kit.AddDependency, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, } return fixture, ctx, func() { cancel() diff --git a/internal/storage/dolt/issue_operations_contract_test.go b/internal/storage/dolt/issue_operations_contract_test.go index 739f376a1..b08dc1257 100644 --- a/internal/storage/dolt/issue_operations_contract_test.go +++ b/internal/storage/dolt/issue_operations_contract_test.go @@ -163,6 +163,24 @@ func TestIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow(t *test conformance.RunIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow(t, ctx, fixture) } +func TestIssueOperationsUpdateStatusCrossingSettlesDependers(t *testing.T) { + fixture, ctx, cleanup := newDoltIssueOperationsFixture(t) + defer cleanup() + conformance.RunIssueOperationsUpdateStatusCrossingSettlesDependers(t, ctx, fixture) +} + +func TestIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t *testing.T) { + fixture, ctx, cleanup := newDoltIssueOperationsFixture(t) + defer cleanup() + conformance.RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t, ctx, fixture) +} + +func TestIssueOperationsClaimLeavesBlockedStateAlone(t *testing.T) { + fixture, ctx, cleanup := newDoltIssueOperationsFixture(t) + defer cleanup() + conformance.RunIssueOperationsClaimLeavesBlockedStateAlone(t, ctx, fixture) +} + func newDoltIssueOperationsFixture(t *testing.T) (conformance.IssueOperationsStagingFixture, context.Context, func()) { t.Helper() store, storeCleanup := setupTestStore(t) diff --git a/internal/storage/dolt/lifecycle_close_reopen_contract_test.go b/internal/storage/dolt/lifecycle_close_reopen_contract_test.go index 6c57ecd4f..327beb6ca 100644 --- a/internal/storage/dolt/lifecycle_close_reopen_contract_test.go +++ b/internal/storage/dolt/lifecycle_close_reopen_contract_test.go @@ -65,6 +65,15 @@ func TestLifecycleCloseReopenContract(t *testing.T) { t.Run("CloseAndReopenRequireActorAndIssueID", func(t *testing.T) { conformance.RunLifecycleCloseAndReopenRequireActorAndIssueID(t, ctx, fixture) }) + t.Run("CloseSettlesItsTransitiveAndCrossPlaneDependers", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesItsTransitiveAndCrossPlaneDependers(t, ctx, fixture) + }) + t.Run("CloseSettlesTheClosedRowItselfAndItsChild", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild(t, ctx, fixture) + }) + t.Run("ReopenReblocksItsDependers", func(t *testing.T) { + conformance.RunLifecycleReopenReblocksItsDependers(t, ctx, fixture) + }) } func newDoltLifecycleCloseReopenFixture(t *testing.T, prefix string) (conformance.LifecycleCloseReopenFixture, context.Context, func()) { diff --git a/internal/storage/embeddeddolt/batch_closer_contract_test.go b/internal/storage/embeddeddolt/batch_closer_contract_test.go index b498affcb..223ef3922 100644 --- a/internal/storage/embeddeddolt/batch_closer_contract_test.go +++ b/internal/storage/embeddeddolt/batch_closer_contract_test.go @@ -127,6 +127,12 @@ func TestEmbeddedBatchCloserDoesNotMutateTheCallerRequest(t *testing.T) { conformance.RunBatchCloserDoesNotMutateTheCallerRequest(t, ctx, newEmbeddedBatchCloserFixture(t, "bcsnapshot")) } +func TestEmbeddedBatchCloserSettlesTheDependersOfWhatItClosed(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunBatchCloserSettlesTheDependersOfWhatItClosed(t, ctx, newEmbeddedBatchCloserFixture(t, "bcblocked")) +} + func newEmbeddedBatchCloserFixture(t *testing.T, prefix string) conformance.BatchCloserFixture { t.Helper() te := newTestEnv(t, prefix) diff --git a/internal/storage/embeddeddolt/deleter_contract_test.go b/internal/storage/embeddeddolt/deleter_contract_test.go index 15db2946f..3876f7a2a 100644 --- a/internal/storage/embeddeddolt/deleter_contract_test.go +++ b/internal/storage/embeddeddolt/deleter_contract_test.go @@ -71,6 +71,12 @@ func TestDeleterContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunDeleterDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("SettlesTheSurvivorsOfADeletedBlocker", func(t *testing.T) { + conformance.RunDeleterSettlesTheSurvivorsOfADeletedBlocker(t, ctx, fixture) + }) + t.Run("SettlesTheChildrenOfADeletedParent", func(t *testing.T) { + conformance.RunDeleterSettlesTheChildrenOfADeletedParent(t, ctx, fixture) + }) } func newEmbeddedDeleterFixture(t *testing.T, te *testEnv, prefix string) conformance.DeleterFixture { diff --git a/internal/storage/embeddeddolt/dependency_editor_contract_test.go b/internal/storage/embeddeddolt/dependency_editor_contract_test.go index a2483e2e2..0ffac34d7 100644 --- a/internal/storage/embeddeddolt/dependency_editor_contract_test.go +++ b/internal/storage/embeddeddolt/dependency_editor_contract_test.go @@ -195,6 +195,30 @@ func TestEmbeddedDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle(t conformance.RunDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "splane")) } +func TestEmbeddedDependencyEditorAddMarksItsSourceInTheSameVerb(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunDependencyEditorAddMarksItsSourceInTheSameVerb(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "bsadd")) +} + +func TestEmbeddedDependencyEditorRemoveUnmarksItsSourceAndDescendants(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunDependencyEditorRemoveUnmarksItsSourceAndDescendants(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "bsrm")) +} + +func TestEmbeddedDependencyEditorMaintainsBlockedStateAcrossPlanes(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunDependencyEditorMaintainsBlockedStateAcrossPlanes(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "bsxp")) +} + +func TestEmbeddedDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t *testing.T) { + skipUnlessEmbeddedDolt(t) + ctx := t.Context() + conformance.RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate(t, ctx, newEmbeddedDependencyEditorFixture(t, ctx, "bsgate")) +} + // newEmbeddedDependencyEditorFixture composes the backend's role fixture kit // with the accessor under test. Every hook but the accessor comes from the kit, // so the seeding and scalar-query plumbing stays identical to the other roles'. @@ -207,11 +231,12 @@ func newEmbeddedDependencyEditorFixture(t *testing.T, ctx context.Context, prefi } kit := newEmbeddedRoleFixtureKit(te, prefix) return conformance.DependencyEditorFixture{ - IssuePrefix: kit.IssuePrefix, - Editor: editor, - CreateIssue: kit.CreateIssue, - CreateWisp: kit.CreateWisp, - QueryScalar: kit.QueryScalar, - CountHistory: kit.CountHistory, + IssuePrefix: kit.IssuePrefix, + Editor: editor, + CreateIssue: kit.CreateIssue, + CreateWisp: kit.CreateWisp, + AddDependency: kit.AddDependency, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, } } diff --git a/internal/storage/embeddeddolt/issue_operations_contract_test.go b/internal/storage/embeddeddolt/issue_operations_contract_test.go index 5a5d5ed76..81277d0aa 100644 --- a/internal/storage/embeddeddolt/issue_operations_contract_test.go +++ b/internal/storage/embeddeddolt/issue_operations_contract_test.go @@ -192,6 +192,27 @@ func TestEmbeddedIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow conformance.RunIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow(t, ctx, newEmbeddedIssueOperationsFixture(t, ctx, te, "claimrestore")) } +func TestEmbeddedIssueOperationsUpdateStatusCrossingSettlesDependers(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "bsupd") + ctx := t.Context() + conformance.RunIssueOperationsUpdateStatusCrossingSettlesDependers(t, ctx, newEmbeddedIssueOperationsFixture(t, ctx, te, "bsupd")) +} + +func TestEmbeddedIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "bscreate") + ctx := t.Context() + conformance.RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t, ctx, newEmbeddedIssueOperationsFixture(t, ctx, te, "bscreate")) +} + +func TestEmbeddedIssueOperationsClaimLeavesBlockedStateAlone(t *testing.T) { + skipUnlessEmbeddedDolt(t) + te := newTestEnv(t, "bsclaim") + ctx := t.Context() + conformance.RunIssueOperationsClaimLeavesBlockedStateAlone(t, ctx, newEmbeddedIssueOperationsFixture(t, ctx, te, "bsclaim")) +} + func newEmbeddedIssueOperationsFixture(t *testing.T, ctx context.Context, te *testEnv, prefix string) conformance.IssueOperationsStagingFixture { t.Helper() operations, err := embeddeddolt.NewIssueOperations(te.store) diff --git a/internal/storage/embeddeddolt/lifecycle_close_reopen_contract_test.go b/internal/storage/embeddeddolt/lifecycle_close_reopen_contract_test.go index 26cab3a3f..1ebd349c7 100644 --- a/internal/storage/embeddeddolt/lifecycle_close_reopen_contract_test.go +++ b/internal/storage/embeddeddolt/lifecycle_close_reopen_contract_test.go @@ -68,6 +68,15 @@ func TestLifecycleCloseReopenContract(t *testing.T) { t.Run("CloseAndReopenRequireActorAndIssueID", func(t *testing.T) { conformance.RunLifecycleCloseAndReopenRequireActorAndIssueID(t, ctx, fixture) }) + t.Run("CloseSettlesItsTransitiveAndCrossPlaneDependers", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesItsTransitiveAndCrossPlaneDependers(t, ctx, fixture) + }) + t.Run("CloseSettlesTheClosedRowItselfAndItsChild", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild(t, ctx, fixture) + }) + t.Run("ReopenReblocksItsDependers", func(t *testing.T) { + conformance.RunLifecycleReopenReblocksItsDependers(t, ctx, fixture) + }) } func newEmbeddedLifecycleCloseReopenFixture(t *testing.T, te *testEnv, prefix string) conformance.LifecycleCloseReopenFixture { diff --git a/internal/storage/uow/batch_closer_contract_test.go b/internal/storage/uow/batch_closer_contract_test.go index 1d4ebbbe2..0f5d5c654 100644 --- a/internal/storage/uow/batch_closer_contract_test.go +++ b/internal/storage/uow/batch_closer_contract_test.go @@ -46,6 +46,7 @@ func TestBatchCloserContract(t *testing.T) { {name: "RecordsOneHistoryEntryForWhatLanded", prefix: "bc-history", run: conformance.RunBatchCloserRecordsOneHistoryEntryForWhatLanded}, {name: "AllRefusedBatchRecordsNoHistory", prefix: "bc-nohistory", run: conformance.RunBatchCloserAllRefusedBatchRecordsNoHistory}, {name: "DoesNotMutateTheCallerRequest", prefix: "bc-snapshot", run: conformance.RunBatchCloserDoesNotMutateTheCallerRequest}, + {name: "SettlesTheDependersOfWhatItClosed", prefix: "bc-blocked", run: conformance.RunBatchCloserSettlesTheDependersOfWhatItClosed}, } { t.Run(test.name, func(t *testing.T) { test.run(t, ctx, newUOWBatchCloserFixture(t, provider, test.prefix)) diff --git a/internal/storage/uow/deleter_contract_test.go b/internal/storage/uow/deleter_contract_test.go index 85b49026a..ad4ad8a18 100644 --- a/internal/storage/uow/deleter_contract_test.go +++ b/internal/storage/uow/deleter_contract_test.go @@ -72,6 +72,12 @@ func TestDeleterContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunDeleterDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("SettlesTheSurvivorsOfADeletedBlocker", func(t *testing.T) { + conformance.RunDeleterSettlesTheSurvivorsOfADeletedBlocker(t, ctx, fixture) + }) + t.Run("SettlesTheChildrenOfADeletedParent", func(t *testing.T) { + conformance.RunDeleterSettlesTheChildrenOfADeletedParent(t, ctx, fixture) + }) } func newUOWDeleterFixture(t *testing.T, ctx context.Context, prefix string) conformance.DeleterFixture { diff --git a/internal/storage/uow/dependency_editor_contract_test.go b/internal/storage/uow/dependency_editor_contract_test.go index 4714d8191..bf445f667 100644 --- a/internal/storage/uow/dependency_editor_contract_test.go +++ b/internal/storage/uow/dependency_editor_contract_test.go @@ -54,6 +54,10 @@ func TestUOWDependencyEditorContract(t *testing.T) { {name: "RefusesBlockingEdgeAcrossAWispHierarchy", run: conformance.RunDependencyEditorRefusesBlockingEdgeAcrossAWispHierarchy}, {name: "RefusesACycleThroughAParentChildHop", run: conformance.RunDependencyEditorRefusesACycleThroughAParentChildHop}, {name: "RefusesASamePlaneEdgeClosingACrossPlaneCycle", run: conformance.RunDependencyEditorRefusesASamePlaneEdgeClosingACrossPlaneCycle}, + {name: "AddMarksItsSourceInTheSameVerb", run: conformance.RunDependencyEditorAddMarksItsSourceInTheSameVerb}, + {name: "RemoveUnmarksItsSourceAndDescendants", run: conformance.RunDependencyEditorRemoveUnmarksItsSourceAndDescendants}, + {name: "MaintainsBlockedStateAcrossPlanes", run: conformance.RunDependencyEditorMaintainsBlockedStateAcrossPlanes}, + {name: "ClosedChildAddSatisfiesAnAnyChildrenGate", run: conformance.RunDependencyEditorClosedChildAddSatisfiesAnAnyChildrenGate}, } { t.Run(test.name, func(t *testing.T) { test.run(t, ctx, fixture) @@ -73,11 +77,12 @@ func newUOWDependencyEditorFixture(t *testing.T, ctx context.Context) conformanc } kit := newUOWRoleFixtureKit(provider, "bd") return conformance.DependencyEditorFixture{ - IssuePrefix: kit.IssuePrefix, - Editor: editor, - CreateIssue: kit.CreateIssue, - CreateWisp: kit.CreateWisp, - QueryScalar: kit.QueryScalar, - CountHistory: kit.CountHistory, + IssuePrefix: kit.IssuePrefix, + Editor: editor, + CreateIssue: kit.CreateIssue, + CreateWisp: kit.CreateWisp, + AddDependency: kit.AddDependency, + QueryScalar: kit.QueryScalar, + CountHistory: kit.CountHistory, } } diff --git a/internal/storage/uow/issue_operations_contract_test.go b/internal/storage/uow/issue_operations_contract_test.go index a44ccece9..1d62b7007 100644 --- a/internal/storage/uow/issue_operations_contract_test.go +++ b/internal/storage/uow/issue_operations_contract_test.go @@ -142,6 +142,21 @@ func TestIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow(t *test conformance.RunIssueOperationsUpdateClaimIsAMutationWhenThePatchRestoresTheRow(t, ctx, newUOWIssueOperationsFixture(t, ctx)) } +func TestIssueOperationsUpdateStatusCrossingSettlesDependers(t *testing.T) { + ctx := context.Background() + conformance.RunIssueOperationsUpdateStatusCrossingSettlesDependers(t, ctx, newUOWIssueOperationsFixture(t, ctx)) +} + +func TestIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t *testing.T) { + ctx := context.Background() + conformance.RunIssueOperationsCreateWithDependenciesSettlesInTheCreatingTransaction(t, ctx, newUOWIssueOperationsFixture(t, ctx)) +} + +func TestIssueOperationsClaimLeavesBlockedStateAlone(t *testing.T) { + ctx := context.Background() + conformance.RunIssueOperationsClaimLeavesBlockedStateAlone(t, ctx, newUOWIssueOperationsFixture(t, ctx)) +} + func newUOWIssueOperationsFixture(t *testing.T, ctx context.Context) conformance.IssueOperationsStagingFixture { t.Helper() operations, provider := newRealIssueOperationsWithProvider(t, ctx) diff --git a/internal/storage/uow/lifecycle_close_reopen_contract_test.go b/internal/storage/uow/lifecycle_close_reopen_contract_test.go index 9ce72900d..99187ed74 100644 --- a/internal/storage/uow/lifecycle_close_reopen_contract_test.go +++ b/internal/storage/uow/lifecycle_close_reopen_contract_test.go @@ -66,6 +66,15 @@ func TestLifecycleCloseReopenContract(t *testing.T) { t.Run("CloseAndReopenRequireActorAndIssueID", func(t *testing.T) { conformance.RunLifecycleCloseAndReopenRequireActorAndIssueID(t, ctx, fixture) }) + t.Run("CloseSettlesItsTransitiveAndCrossPlaneDependers", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesItsTransitiveAndCrossPlaneDependers(t, ctx, fixture) + }) + t.Run("CloseSettlesTheClosedRowItselfAndItsChild", func(t *testing.T) { + conformance.RunLifecycleCloseSettlesTheClosedRowItselfAndItsChild(t, ctx, fixture) + }) + t.Run("ReopenReblocksItsDependers", func(t *testing.T) { + conformance.RunLifecycleReopenReblocksItsDependers(t, ctx, fixture) + }) } func newUOWLifecycleCloseReopenFixture(t *testing.T, ctx context.Context, prefix string) conformance.LifecycleCloseReopenFixture { diff --git a/issueops/batchcloser.go b/issueops/batchcloser.go index 16751aece..f557a791b 100644 --- a/issueops/batchcloser.go +++ b/issueops/batchcloser.go @@ -134,6 +134,12 @@ type CloseBatchResult struct { // is restricted: the close itself lands on the ephemeral row, reads back from // it, and counts toward ClaimNext's coupling like any other landing. // +// WHAT LANDS MAINTAINS BLOCKED STATE under BlockedStateInvariant: every item +// that actually closed leaves its dependers — and everything that inherits +// from them, in both planes — settled in the SAME transaction the batch +// commits, so a ClaimNext running after the closes sees the state those closes +// produced rather than the state that preceded them. +// // Implementations never mutate caller-owned request values, snapshot the // request at method entry, and apply validation and normalization only to // attempt-local clones. Deterministic request-validation failures match diff --git a/issueops/blockedstate.go b/issueops/blockedstate.go new file mode 100644 index 000000000..49daf2a92 --- /dev/null +++ b/issueops/blockedstate.go @@ -0,0 +1,55 @@ +package issueops + +// BlockedStateInvariant is the canonical statement of what the mutating roles +// in this package promise about BLOCKED STATE, and the only statement a +// conformance case may assert against. Cite it BY SYMBOL: it is a doc anchor +// precisely so a citation cannot rot the way a file:line one does. +// +// Blocked state is DERIVED AND PERSISTED. It is a function of the current +// dependency graph and the current statuses of both planes, and it is also +// stored on the row, which is what makes it assertable at all — and what makes +// asking a role "is this issue blocked?" the wrong way to check it. A backend +// that answered correctly from the live graph and never wrote the column would +// satisfy every role answer and none of the clauses below. +// +// THE PREDICATE. A row that is closed or pinned is never blocked. Any other row +// is blocked exactly when at least one of these holds: +// +// - it has a blocks or conditional-blocks edge onto a target that is itself +// neither closed nor pinned; +// - it is the child of a parent-child edge whose parent is blocked, so +// blockage is INHERITED down a hierarchy transitively; +// - it has a waits-for edge whose gate over the spawner's children is not yet +// satisfied. +// +// Edges and inheritance cross the two planes in BOTH directions: an issue may +// be blocked by a wisp and a wisp by an issue, and a parent in either plane +// propagates to a child in either. The exact gate vocabulary (all-children, +// any-children, also_blocks) is the derivation engine's, not this doc's; a role +// contract pins that a gate is CONSULTED, not how it reads. +// +// THE LOCAL-WRITE CLAUSE — transactional, not eventual. Every role method that +// commits a mutation leaves blocked state consistent with the predicate FOR THE +// ROWS ITS MUTATION COULD HAVE AFFECTED, inside its own transaction, before it +// commits. There is no queue, no follow-up pass and no window: a caller that +// reads the column immediately after the verb returns reads the settled value. +// The affected rows are not only the row named in the request — closing a +// blocker settles its dependers, and settling a row settles that row's +// parent-child descendants, in both planes, to a fixpoint. +// +// THE MERGE CLAUSE — eventual, with a named repair. A merge taken during a pull +// bypasses the local write paths, so blocked state after a merge is settled by +// a scoped recompute that follows the merge rather than by the merge itself. If +// that recompute is skipped or fails, stale values persist until the next pull +// widens its window or an operator runs the full repair. This is the ONE clause +// under which a stale column is admissible, and no role method can produce that +// state. +// +// THE NON-PERTURBATION CLAUSES. Settling blocked state is not a user edit: it +// never bumps a row's updated_at, so a flip does not make a synced row look +// hand-edited to a stale-guard or a conflict-guard. It is idempotent on a +// consistent database — a verb that changes nothing settles nothing — and it +// never reaches rows outside the affected set, so an unrelated blocked row is +// still blocked, for the same reason, after a neighboring claim or comment. +const BlockedStateInvariant = "is_blocked equals the fixpoint of the blocking predicate over the current graph, on both planes, " + + "at the end of every committing mutation, without bumping updated_at" diff --git a/issueops/deleter.go b/issueops/deleter.go index 4a9f2035f..8cf5e8369 100644 --- a/issueops/deleter.go +++ b/issueops/deleter.go @@ -217,6 +217,14 @@ func (e *NotFoundError) Unwrap() error { return ErrNotFound } // internal/hooks publishes on_create, on_update and on_close and none of them // names a deletion. // +// A DELETION MAINTAINS BLOCKED STATE under BlockedStateInvariant. The rows it +// erases are gone, so the promise is about the SURVIVORS: a row whose only +// blocker was deleted is left unblocked, and so is everything that inherited +// that block from it, inside the deleting transaction. This is the same +// obligation the reference rewrite has and for the same reason — a survivor +// left pointing at an absent row, or left blocked by one, is the state the +// unforced guard exists to prevent a caller from creating by hand. +// // Deterministic request-validation failures match ErrValidation. Result values // are unspecified when error is non-nil. type Deleter interface { diff --git a/issueops/dependencyeditor.go b/issueops/dependencyeditor.go index 3555de67f..2951dd66e 100644 --- a/issueops/dependencyeditor.go +++ b/issueops/dependencyeditor.go @@ -125,6 +125,11 @@ type RemoveDependencyResult struct { // A TARGET's plane is independent of its source's: either class may depend on // the other. // +// EITHER METHOD MAINTAINS BLOCKED STATE under BlockedStateInvariant: an edge +// that lands or is removed leaves the column settled — for the source, for +// everything that inherits from it, and for any waiter whose gate the edge +// changed — inside the same transaction that wrote the edge. +// // EACH METHOD LEAVES A TRAIL IN THE SOURCE'S EVENT STREAM, attributed to the // request's Actor: a genuinely new edge records a dependency_added entry, and // a removal that found its edge a dependency_removed one. Work that wrote diff --git a/issueops/issueops.go b/issueops/issueops.go index c49c6c1e5..4f5aa23b3 100644 --- a/issueops/issueops.go +++ b/issueops/issueops.go @@ -390,6 +390,12 @@ type ReopenResult struct { // Lifecycle describes guarded issue mutations. A new capability gets a new // role interface and its own accessor; never append a method here. +// +// EVERY VERB HERE MAINTAINS BLOCKED STATE under BlockedStateInvariant: a +// Create that carries edges, and an Update or Close or Reopen that moves a +// status across the closed/pinned boundary, leave the column settled for every +// row their mutation could have affected before the transaction commits. +// // Deterministic request validation failures match ErrValidation; when a // more-specific validation sentinel applies, it remains matchable too. // Implementations never mutate