feat(gates): gate-64 apphost-autoload-prelude — AppHost adoption without OpenRegister's autoloader

[rubenvdlinde]

What this gate catches

OC_App::getEnabledApps() does sort($apps), and Coordinator::registerApps() walks that sorted list calling OC_App::registerAutoloading($appId, $path) and then $application->register() for one app at a time.

So every app's register() runs before the PSR-4 prefix of every alphabetically-later app exists. Any leaf whose app id sorts before openregister reaches register() while OCA\OpenRegister\ is not autoloadable — on a healthy instance, with OpenRegister enabled.

Two shapes, both quiet:

• Guarded — class_exists('OCA\OpenRegister\AppHost\...') answers FALSE, the generic plumbing is skipped, and classes that exist ONLY as Bootstrap DI aliases (Controller\HealthController → AppHost\Controller\GenericHealthController) fail to resolve. Those endpoints return 500, not 404.
• Unguarded — the \Error aborts the entire register(). Every registerEventListener below it never runs. Coordinator catches the Throwable, logs an emergency and continues, so the app stays enabled and keeps serving.

Measured twice, independently: doriath (the audit listener recorded ZERO dispatched events) and openconnector, whose own source records class_exists at register(): false on a clean install — removing that guard took its flow-node registry from 10 nodes to 12.

Why a gate and not a test

The failure depends on which apps happen to be installed. Any app that pulls OpenRegister's autoloader in registers the prefix process-wide, masking the defect for every app that registers after it. On a dev instance with such an app present everything resolves; in CI with a minimal app set it does not. A masking app makes the failure vanish exactly where you would test for it.

Proof it goes RED

Not shipped green-only. Verified at both levels.

Helper, against REAL fleet code — doriath at origin/development (the pre-fix include_once ../../../openregister/vendor/autoload.php workaround, no registerAutoloading):

FAIL doriath-before: lib/AppInfo/Application.php references OCA\OpenRegister\AppHost\Bootstrap,
but nothing under lib/AppInfo/ registers OpenRegister's autoloader first. ...
1 AppHost adoption(s) without the autoload prelude.
rc=1

The same app with the prelude applied (ConductionNL/doriath#162) → apphost-autoload-prelude: OK, rc=0.

Through the actual runner (run-hydra-gates.sh, not just the helper — a working helper and a reporting gate are different things):

[gate-64] apphost-autoload-prelude: FAIL — 1 AppHost adoption(s) with no OpenRegister autoload prelude (ADR-040)
[hydra-gates] COVERAGE: 34 of 64 declared gates reported a result

[gate-64] apphost-autoload-prelude: PASS                     # fixed app
[gate-64] apphost-autoload-prelude: NOT APPLICABLE — no lib/AppInfo/ ...   # no composition root

The declared inventory moved 63 → 64 on its own, so the gate is counted by the coverage accounting rather than being invisible.

Unit suite — scripts/lib/test_check_apphost_autoload_prelude.py, 11 tests, auto-discovered by tests/run-helper-suites.sh (19 passed / 0 failed / 2 documented quarantines with this branch applied). It writes a known-bad app, asserts RED, then adds the prelude to the same app and asserts GREEN.

One of those tests caught a real bug in the helper before it shipped: apphost-prelude\s+exclude\s+(?P<reason>\S.*) used \s, which matches a newline — so a bare // apphost-prelude exclude swallowed the next line of source as its "reason" and bought a free pass. The separator is now [ \t], and a reasonless annotation fails like any other unguarded adoption.

False-positive check across the fleet

Ran against the real lib/AppInfo/ of 18 apps on their development branches. Only pre-fix doriath flags. openregister is exempt by namespace (it owns AppHost), not by directory name. Lazy container closures that merely mention an AppHost class are deliberately not flagged — their bodies run long after every app has registered.

Heads-up for consumers

The fleet pins hydra-gates-ref: v1.3.0 in each consumer's code-quality.yml, so this gate does nothing until a consumer-ref sweep moves them. That sweep is deliberately not part of this PR — four agents are mid-flight on app repos tonight and changing their CI underneath them would be reckless.

When the sweep happens, a read-only dry run says openbuild and scholiq will go RED (both call Bootstrap::register with no prelude); decidesk and shillinq are green. Those four repos were left untouched here.

Also not done here: no git tag is cut, and no hydra-gate-apphost-autoload-prelude skill was added to the hydra repo alongside the other gate skills — both belong with the sweep.