Conferring a product on two ladders writes its tier-change rows in no fixed order, so a golden test fails now and then #218

New Issue

2026-10-12T02:10:18Z

cgalo5758 commented

2026-10-12 02:10:18 +00:00

What a contributor runs into

TestPlanActsGolden/default-already-at in internal/server has failed once with two rows of its expected output (internal/server/testdata/plan_acts/default-already-at.json) in swapped order, and it passes when run again.

A plan ladder is an ordered list of tiers, each tier a product, and a product can sit on more than one ladder. Every tier change an organization's pool goes through is a row in core.pool_provision_transitions. In this test the default product, Basic, sits on two ladders, Main and Twin. Placing the organization on its type's default plan confers Basic once, through core.confer, which writes one initiate row for each ladder. The golden expects Main's row first; the failing run listed Twin's first.

The test lists the rows ORDER BY transition_id (internal/server/plan_acts_golden_db_test.go:397). Transition ids come from uuidv7() and rise in the order the rows are written, so the golden's order is the write order. core.confer (internal/db/migrations/00023_grant_resumption.sql) writes the new position's rows in a loop over the product's ladders, FOR v_shape IN SELECT ... FROM core.product_conferral_shapes (line 634), with one INSERT per ladder (line 661). That query has no ORDER BY, so the ladders come in whatever order the query plan returns them. The loop that writes the end rows of a provision the conferral replaces (line 602) has no ORDER BY either, so a replaced provision on two ladders is ended in either order too.

Why it costs

A golden that fails by chance teaches people to rerun it, and a real change to the row order then gets rerun too. The order reaches more than this test: two other tests list transitions by transition id (internal/entitlements/grant_resumption_fixture_test.go:460, internal/fulfillment/trace_db_test.go:371), and the Tier changes list breaks its ties on the transition id (ListTransitionsByPool in internal/entitlements/queries/pool_provision_transitions.sql), so it can show the rows one conferral writes for two ladders in either order.

Where

core.confer in internal/db/migrations/00023_grant_resumption.sql; internal/server/plan_acts_golden_db_test.go.

Done when

core.confer writes the rows of one conferral in ladder order: both loops order by the ladder id, in a new migration that replaces the function, with a Down that restores today's body. Ladder ids are uuidv7() as well, so the rows follow the order the ladders were created, which is the order default-already-at expects; its golden does not change.

The other fix is a golden query that does not depend on write order, sorting by a key such as the provision, the transition type and the ladder. It fixes this test alone, reorders every plan-act golden that lists transitions, and leaves the other two tests and the Tier changes list as they are. The migration is the better fix.

Related: #179 asks for an id shared by the rows one act writes; that id would group them, not order them.

## What a contributor runs into `TestPlanActsGolden/default-already-at` in `internal/server` has failed once with two rows of its expected output (`internal/server/testdata/plan_acts/default-already-at.json`) in swapped order, and it passes when run again. A plan ladder is an ordered list of tiers, each tier a product, and a product can sit on more than one ladder. Every tier change an organization's pool goes through is a row in `core.pool_provision_transitions`. In this test the default product, Basic, sits on two ladders, Main and Twin. Placing the organization on its type's default plan confers Basic once, through `core.confer`, which writes one `initiate` row for each ladder. The golden expects Main's row first; the failing run listed Twin's first. The test lists the rows `ORDER BY transition_id` (`internal/server/plan_acts_golden_db_test.go:397`). Transition ids come from `uuidv7()` and rise in the order the rows are written, so the golden's order is the write order. `core.confer` (`internal/db/migrations/00023_grant_resumption.sql`) writes the new position's rows in a loop over the product's ladders, `FOR v_shape IN SELECT ... FROM core.product_conferral_shapes` (line 634), with one INSERT per ladder (line 661). That query has no ORDER BY, so the ladders come in whatever order the query plan returns them. The loop that writes the `end` rows of a provision the conferral replaces (line 602) has no ORDER BY either, so a replaced provision on two ladders is ended in either order too. ## Why it costs A golden that fails by chance teaches people to rerun it, and a real change to the row order then gets rerun too. The order reaches more than this test: two other tests list transitions by transition id (`internal/entitlements/grant_resumption_fixture_test.go:460`, `internal/fulfillment/trace_db_test.go:371`), and the Tier changes list breaks its ties on the transition id (`ListTransitionsByPool` in `internal/entitlements/queries/pool_provision_transitions.sql`), so it can show the rows one conferral writes for two ladders in either order. ## Where `core.confer` in `internal/db/migrations/00023_grant_resumption.sql`; `internal/server/plan_acts_golden_db_test.go`. ## Done when `core.confer` writes the rows of one conferral in ladder order: both loops order by the ladder id, in a new migration that replaces the function, with a Down that restores today's body. Ladder ids are `uuidv7()` as well, so the rows follow the order the ladders were created, which is the order `default-already-at` expects; its golden does not change. The other fix is a golden query that does not depend on write order, sorting by a key such as the provision, the transition type and the ladder. It fixes this test alone, reorders every plan-act golden that lists transitions, and leaves the other two tests and the Tier changes list as they are. The migration is the better fix. Related: #179 asks for an id shared by the rows one act writes; that id would group them, not order them.

cgalo5758 added the

kind

debt

area/entitlements area/testing labels 2026-10-12 02:10:18 +00:00

cgalo5758 referenced this issue

2026-10-16 01:56:23 +00:00

List queries can end their sort on a column two rows share, and nothing checks the last sort key #225

cgalo5758 referenced this issue from a commit

2026-10-16 05:01:40 +00:00

Write down where a rule and an act live, output order, and how to prove a test

Sign in to join this conversation.