Serialize the live classes that share the store, document the ones that do not (#1776)

[erikdarlingdata]

Closes #1776.

I verified the issue's classification against the source rather than applying it, and it moved in both directions: one aggressor was missed, and three of the six were substring false positives.

Corrected classification

Class	Issue said	Verified	Action
StoreConfigProviderTests	shared	shared	attribute
DarlingEndpointToggleCliTests	shared	shared	attribute
ExcludedDatabasesStoreLiveTests	shared	shared	attribute
DarlingComposeTests	not listed	shared, runs DDL	split + attribute
DarlingAlertTuningKnobsTests	not listed	own database (ScratchPostgres)	marker
DarlingDeliveryModeTests	not listed	own database (ScratchPostgres)	marker
DarlingManagedPostgresTests	"own cluster"	never reads DARLING_TEST_PG	marker, corrected reason
DarlingStoreUpgradeTests	"own cluster"	never reads DARLING_TEST_PG	marker, corrected reason
DarlingPgRuntimeVersionPinTests	"probes the bundle"	never reads DARLING_TEST_PG	marker, corrected reason
PayloadDimensionTests	not listed	prose mention only	out of scope, like AlertEngineTests

The missed aggressor is the significant one. DarlingComposeTests.RunComposedPanel_OldWindow_AgainstPlainPostgres_RunsCleanOnRaw connects straight to the shared database and runs PgMigrations.MigrateAsync against it — DDL, concurrently with the sixty-odd serialized classes. That makes it the most aggressive of the four, and it was not on the list.

Three of the six were a substring artifact. DarlingManagedPostgresTests, DarlingStoreUpgradeTests and DarlingPgRuntimeVersionPinTests read DARLING_TEST_PGRUNTIME (and _OLD / _NEWZIP) — different variables that merely share the prefix with DARLING_TEST_PG. They never touch the shared store at all. "Do not serialize them" was the right answer reached for the wrong reason, so the comment on each records which reason actually applies; otherwise the next sweep re-derives the same false positive.

The judgement call on DarlingComposeTests

It does not take the attribute directly. The class holds 127 tests, 126 of them pure, and dragging all of them into the serialized collection to protect one live test is exactly the "slow the suite for no safety gain" the issue warns about. The live test is split into DarlingComposeLivePostgresTests, which is the shape 44 other files in this project already use (counted, not estimated): a ...SurfaceAndSqlTests / ...LivePostgresTests pair. The parent class's doc comment already claimed "the live compile-and-run round-trip is exercised against a real store elsewhere" — that is now true rather than aspirational.

Why the rollback comments did not make those classes safe

Two of the three serialized classes documented themselves as "transaction-rolled-back so they never clobber a shared dev store's singleton config rows", which reads like an exemption and is not one. Rolling back protects the data, not the concurrency: an uncommitted write still holds its row locks for the life of the transaction and still fires the config_version bump trigger. That is recorded on each class, because the next reader will otherwise draw the same wrong conclusion the comment invites.

The meta-test

LivePostgresCollectionHygieneTests requires every class that reads the shared store to either carry [Collection("live-postgres")] or record an #1776 own-store exemption. It demands a decision, not the attribute — a class that mints its own database genuinely should not serialize.

Two details that matter:

• It matches the quoted literal "DARLING_TEST_PG", not a substring. That is what keeps DARLING_TEST_PGRUNTIME out, and it also keeps out doc-comment prose (which writes the name bare), so a class that merely describes the variable is not dragged in. Matching the way the issue's original sweep did would make this test permanently red on three innocent classes.
• It fails rather than skips when it cannot find the tree, following DocCommentHygieneTests: a guard that silently skips is a guard that silently stops guarding.

The failure message names each offender with file and line and spells out both remedies, including the recommendation to split rather than serialize a mostly-pure class.

Mutation

#	Mutation	Result
M4	Remove [Collection("live-postgres")] from StoreConfigProviderTests	RED: StoreConfigProviderTests.cs:35 StoreConfigProviderTests, followed by the "Pick one, deliberately" guidance

Worth noting what M4 also proved: the explanatory comment left on the serialized classes begins #1776: while the exemption marker is #1776 own-store, and the guard correctly refused to accept the former as an exemption. The two markers do not collide.

Verification

• Darling.Tests full suite against a live PostgreSQL 18 + TimescaleDB 2.28.1 rig: 3649 passed, 0 failed, 7 skipped (base plus the one new meta-test; the compose split moves tests between classes without changing the count).
• Meta-test green on the fixed tree, red under M4.
• Build: dotnet build Darling/Darling.Tests/Darling.Tests.csproj -c Debug -t:Rebuild — 0 Warning(s), 0 Error(s).

No production code is touched; this is test infrastructure only.

🤖 Generated with Claude Code