beads/issueops/blockedstate.go
Julian Knutsen 25b055e038
Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436)
is_blocked is derived AND persisted. Three deduplication slices independently
flagged it: contract cases read the raw column as a precondition, one calling
that read load-bearing, but nothing pinned that the recompute itself is correct.

13 cases across five role contracts, wired at all three legs.

Not its own role, deliberately. The recompute fails the repo's role test — no
caller asks it as a question and no accessor reaches it. BlockedRecomputer is
the separate repair verb, already pinned. And role-ifying it would not close the
gap: it would contract-test a body shared verbatim by every mode, and would
still pass on a backend that never denormalized on write. The divergence surface
is per-role WIRING, hand-mirrored between issueops/ and domain/db/, and only
role cases run that wiring on all three legs.

The promise existed nowhere a contract could cite. It is now
issueops.BlockedStateInvariant, cited by symbol rather than line, stating the
predicate, the local-write clause (settled for every AFFECTED row inside the
mutating transaction — affected is not just the named row), the merge clause,
and the non-perturbation clauses.

One of this programme's cannot-fail tests was this very column: seeded to 1 with
no blocker edge, so the guard short-circuited and it could never fail on its own
term. The shared kit forecloses that structurally. No hook writes the flag —
every state is built through role verbs. watchFlip fails the test if the
pre-value already equals the value being asserted. Every case carries a
non-flipping control. Blocked preconditions pin the flag AND the edge facts.

Review then proved a stated clause had no case at all: deleting the crossing row
from its own affected set left Close, Reopen and Update-crossing all green,
because every fixture happened to make the crossing row unblocked and no fixture
hung a child off the row being closed. That regression strands a stale flag no
verb can repair. Now covered by a forced close of a row that is itself blocked
and carries a child, both subjects flipping.

Review also caught, and CI caught, a case asserting the claimed row was
untouched when a claim writes that row by design — it passed locally only
because updated_at is DATETIME at second precision. Narrowed to what the verb
actually promises, and the remaining flag control verified to still redden.

Recorded, not fixed: conditional-blocks edges are accepted by the probe but
never seeded; waits-for gates are pinned only on the add side; wisp-blocker
deletion is unpinned.
2026-08-08 11:23:34 -07:00

55 lines
3.3 KiB
Go

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"