ci: gate pull requests on a worker-mode state audit

Changes

- Add `igor-php/igor-php` as a dev dependency and register `IgorPhpBundle` in dev
- Configure it in `igor.json`: project scope, dev environment, baseline file
- Record the 33 existing findings in `igor-baseline.json`, each with a reason
- Add `composer worker-state-check` and `worker-state-baseline`, and a
  `Worker state audit` job to the review workflow

Why

The statelessness rules the last few commits established are the kind that decay
without enforcement, and they matter whether or not worker mode is ever switched
on: `messenger:consume` is already long-running in production.

igor-php audits every shared service in the compiled container rather than
grepping for patterns, which is why it caught the `AdminUrlGenerator` mutations
that reading `src/` for stateful properties had missed. Against that, roughly two
thirds of its project findings are noise — mostly Doctrine entities returned from
a repository, which it reads as shared services — so it is only usable behind a
baseline. Vendor code is out of scope: it reported 341 findings there, none of
them ours to fix.

Every baseline entry carries a reason rather than the generated TODO, so the file
documents why each is safe instead of just silencing it. Verified the gate is
live: introducing a stateful property on a service fails the audit, and removing
it passes.

Author: turegjorup

.github/workflows/pr.yaml

@@ -18,6 +18,27 @@ jobs:
                   docker compose run --rm frankenphp composer install --no-interaction
                   docker compose run --rm frankenphp vendor/bin/phpstan analyse
 
+    worker-state:
+        runs-on: ubuntu-latest
+        name: Worker state audit
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v6
+
+            - name: Create docker network
+              run: docker network create frontend
+
+            # igor-php audits every shared service in the compiled container for
+            # state that would leak between requests in a worker. It reads the
+            # service map IgorPhpBundle writes during cache:clear, and fails only
+            # on findings absent from igor-baseline.json — every entry in which
+            # carries a reason. Regenerate with `composer worker-state-baseline`.
+            - name: Audit shared services for worker-mode state leaks
+              run: |
+                  docker compose run --rm frankenphp composer install --no-interaction
+                  docker compose run --rm frankenphp bin/console cache:clear
+                  docker compose run --rm frankenphp composer worker-state-check
+
     phpunit:
         runs-on: ubuntu-latest
         name: PHP Unit tests

CHANGELOG.md

@@ -47,6 +47,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     consumer, which in a worker outlives the request
   - Cover all of it with tests: the factories had none, and neither the
     dashboard nor the Security Contract CRUD was in the admin smoke test
+  - Gate pull requests on `igor-php`, which audits every shared service in the
+    compiled container for state that would leak between requests.
+    `igor-baseline.json` records the 33 existing findings with a reason each, so
+    the job fails only on new ones; vendor code is out of scope
   - Document worker mode and the statelessness it requires in `README.md` and
     `claude.md`. It stays off: measured here it gives roughly 20% more requests
     per second on `/admin` and half the median latency, but around 40% fewer on

README.md

@@ -188,6 +188,27 @@ deliberate, implement `Symfony\Contracts\Service\ResetInterface` –
 For an object you do not own, clear it at the call site, the way every
 `AdminUrlGenerator` chain here opens with `unsetAll()`.
 
+That rule is enforced. [igor-php](https://github.com/igor-php/igor-php) audits
+every shared service in the compiled container for state that would leak between
+requests, and runs on every pull request:
+
+```sh
+docker compose exec frankenphp composer worker-state-check
+```
+
+Existing findings live in `igor-baseline.json`, so the job fails only on new
+ones. Every entry there carries a reason – most are Doctrine entities returned
+from a repository, which igor reads as shared services, and `AdminUrlGenerator`
+chains it cannot see are already cleared by `unsetAll()`. Read the reasons before
+adding to them; if a finding is genuine, fix it rather than baseline it. After a
+deliberate change, regenerate with `composer worker-state-baseline` and write a
+reason for each new entry.
+
+The audit needs the service map that `IgorPhpBundle` writes during
+`cache:clear`, so run that first if the cache is cold. Vendor code is out of
+scope (`ignore_vendors` in `igor.json`): it reported 341 findings there, none of
+them ours to fix.
+
 `FRANKENPHP_RESET_KERNEL=1`, on Symfony 8.1 and later, clones the kernel between
 requests instead. It hides this class of bug at the cost of a boot per request,
 which is most of what worker mode is for – useful to compare against, not to

claude.md

@@ -119,6 +119,12 @@ Things that break a worker and have no place here: `exit()`/`die()`, writes to
 superglobals, `__destruct()` on a shared service, and mutable `static`
 properties.
 
+`composer worker-state-check` audits this with igor-php and runs on every pull
+request. `igor-baseline.json` holds the known findings, each with a reason, so
+the job fails only on new ones — fix a genuine finding rather than baselining
+it, and regenerate with `composer worker-state-baseline` only after a deliberate
+change.
+
 `FRANKENPHP_RESET_KERNEL=1` (Symfony 8.1+) clones the kernel between requests
 and papers over all of this, at the cost of a boot per request. Treat it as a
 measurement baseline, not a fix.

composer.json

@@ -47,6 +47,7 @@
         "ergebnis/composer-normalize": "^2.23",
         "friendsofphp/php-cs-fixer": "^3.6",
         "hautelook/alice-bundle": "^2.14",
+        "igor-php/igor-php": "^0.9.5",
         "justinrainbow/json-schema": "^6.0",
         "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan": "^2.1",
@@ -136,6 +137,12 @@
         "update-api-spec": [
             "bin/console api:openapi:export --output=public/api-spec-v1.yaml --yaml --no-interaction",
             "bin/console api:openapi:export --output=public/api-spec-v1.json --no-interaction"
+        ],
+        "worker-state-baseline": [
+            "vendor/bin/igor-php --generate-baseline ."
+        ],
+        "worker-state-check": [
+            "vendor/bin/igor-php ."
         ]
     }
 }

composer.lock

@@ -23,4 +23,5 @@
     Twig\Extra\TwigExtraBundle\TwigExtraBundle::class => ['all' => true],
     Symfony\UX\TwigComponent\TwigComponentBundle::class => ['all' => true],
     Doctrine\Bundle\MigrationsBundle\DoctrineMigrationsBundle::class => ['all' => true],
+    IgorPhp\IgorBundle\IgorPhpBundle::class => ['dev' => true],
 ];