Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs: drop dedicated test name from collision coverage notes (#21124)

p0nyd634c8350974
diff --git a/AGENTS.md b/AGENTS.md
index b0b9a3f432..5084f1adcc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -210,13 +210,13 @@ When writing or modifying queries on these tables:
`TestCollision_*` test in `backend/tests/`. The existing `setupCollidingProjects`
fixture and `assertProjectUnchanged` helper cover `plan`, `issue`, `task`, `task_run`,
`plan_check_run`, `task_run_log`, `db_group`, and `release` (the snapshot reads the
- last three through public APIs where one exists). `plan_webhook_delivery` is covered
- by the dedicated `TestCollision_PlanWebhookDeliveryWrite` with a table-specific raw
- metadata-DB read and explicit stabilization — its rows are claimed asynchronously
- after rollout completion, so it is deliberately kept out of the generic snapshot to
- avoid spurious cross-project-leak failures. For any future composite-PK table
- outside that set, write table-specific seed and assertion helpers — or extend the
- shared helper first
+ last three through public APIs where one exists). `plan_webhook_delivery` has no
+ public read API and uses a table-specific raw metadata-DB read; its rows are
+ claimed asynchronously after rollout completion, so raw-read collision tests
+ must stabilize before snapshotting and compare the table separately (see
+ `backend/tests/README.md`). For any future composite-PK table outside that set,
+ write table-specific seed and assertion helpers — or extend the shared helper
+ first
- Collision tests use `setupCollidingProjects` + `fixture.completeRolloutB` for setup
and `snapshotProject` / `assertProjectUnchanged` for assertions — all going through
the public gRPC API, no store access. Run with:
diff --git a/backend/tests/README.md b/backend/tests/README.md
new file mode 100644
index 0000000000..f5f135eda1
--- /dev/null
+++ b/backend/tests/README.md
@@ -0,0 +1,24 @@
+# Backend integration tests
+
+Public v1 API tests backed by real PostgreSQL live here. Cross-Project
+collision tests use `setupCollidingProjects` plus `snapshotProject` /
+`assertProjectUnchanged` from `collision_helper_test.go` (see
+`docs/pre-pr-checklist.md` step 3 for the full contract).
+
+## plan_webhook_delivery collision coverage
+
+`plan_webhook_delivery` has no public gRPC read API, so collision coverage reads
+the table directly from the metadata DB. Two extra requirements apply to any
+test for a writer of this table:
+
+- Delivery rows are claimed asynchronously after rollout completion. Wait for
+ the project's delivery row set to stabilize before taking the baseline
+ snapshot, and again before the post-operation snapshot.
+- `assertProjectUnchanged` intentionally does NOT compare
+ `PlanWebhookDeliveries`. The test must assert those rows separately with its
+ own stabilized comparison.
+
+`TestCollision_PlanWebhookDeliveryWrite` demonstrates both requirements.
+Without them, a raw-row snapshot that only calls `assertProjectUnchanged`
+produces false-positive coverage: a cross-project write to this composite-PK
+table would go undetected.
diff --git a/docs/pre-pr-checklist.md b/docs/pre-pr-checklist.md
index 4e36b4f5d3..30d2ee45cc 100644
--- a/docs/pre-pr-checklist.md
+++ b/docs/pre-pr-checklist.md
@@ -90,13 +90,14 @@ If the diff adds or modifies a store method that touches a composite-PK table:
2. If not, add one using `setupCollidingProjects` and `assertProjectUnchanged` from
`backend/tests/collision_helper_test.go`. The shared snapshot covers `plan`,
`issue`, `task`, `task_run`, `plan_check_run`, `task_run_log`, `db_group`, and
- `release` (public APIs where one exists). `plan_webhook_delivery` is covered by the
- dedicated `TestCollision_PlanWebhookDeliveryWrite` with a table-specific raw
- metadata-DB read and explicit stabilization — its rows are claimed asynchronously
- after rollout completion, so it is deliberately kept out of the generic snapshot to
- avoid spurious cross-project-leak failures. For methods touching any future table
- outside that set, add table-specific assertions inline — or extend the shared
- helper first
+ `release` (public APIs where one exists). `plan_webhook_delivery` has no public
+ read API and uses a table-specific raw metadata-DB read; its rows are claimed
+ asynchronously after rollout completion, so raw-read tests must stabilize the
+ row set before snapshotting and compare the table separately —
+ `assertProjectUnchanged` does not compare `PlanWebhookDeliveries`. See
+ `backend/tests/README.md` for the pattern. For methods touching any future
+ table outside that set, add table-specific assertions inline — or extend the
+ shared helper first
3. If your test needs project B rolled out (to create task/task_run/plan_check_run
rows that could collide with project A's), call `fixture.completeRolloutB(ctx, t, ctl)`
— this is the ONLY supported rollout path and it proves `task` and `task_run`