Alternative direction to #19440, picking up LordSimal's review there: instead of narrowing the union and patching covariance, split the hydrated and non-hydrated read paths at the source so the union never has to exist.

Summary

Adds Table::findUnhydrated() + a Cake\ORM\Query\SelectUnhydratedQuery class. Hydrated and non-hydrated reads get separate entry points with separate static types — find() keeps the typed SelectQuery<TEntity> the common path always wanted; the rare array path moves to a class whose type matches its runtime.

// Hydrated, default — type system knows you get an entity.
$user = $usersTable->find()->where(['id' => 1])->first();         // User|null

// Non-hydrated, explicit — type system knows you get an array.
$row  = $usersTable->findUnhydrated()->where(['id' => 1])->first(); // array<string, mixed>|null

Motivation

In real consumer code find()->first() is User|array|null, so anything entity-shaped trips PHPStan even though the caller never opted into disableHydration(). This splits the two shapes at construction so the common path stays clean and the array path is honestly typed.

Design — the class is a static-typing vehicle, nothing more

SelectUnhydratedQuery extends SelectQuery<array<string, mixed>>:

• Constructor sets _hydrate = false. No behavioral overrides. It is fully substitutable for SelectQuery — runtime behavior is identical to find()->disableHydration(), so eager loading, association finders and the rest of the ORM treat it like any other select query.
• Its entire value is the static type: first() / firstOrFail() / all() / toArray() / iteration resolve to arrays instead of entity|array, and crucially that binding survives finder dispatch, where a bare SelectQuery<array<string, mixed>> annotation would decay (every custom finder is typed findFoo(SelectQuery): SelectQuery with no generic; core's own find() needs a manual var-cast annotation after callFinder() for exactly this reason).

Table::findUnhydrated(string $type = 'all', ...): SelectUnhydratedQuery:

• Builds through the QueryFactory via the new Table::selectUnhydratedQuery() / QueryFactory::selectUnhydrated() seam, so a custom injected QueryFactory is honored exactly like it is for find().
• Dispatches through callFinder() like find() — any userland custom finder is reused as-is, zero finder duplication.
• A finder that discards the passed query and returns a fresh one cannot preserve the contract; it fails with a clear CakeException naming the finder, instead of a cryptic return-type TypeError. This guard lives only at the public entry point, isolated from ORM internals.

SelectQuery::disableHydration() gets a docblock deprecation marker (5.next) pointing at findUnhydrated(); no runtime trigger. Targeted for removal in 6.0.

Naming

findUnhydrated() / SelectUnhydratedQuery keeps the vocabulary consistent with the existing enableHydration() / disableHydration() / isHydrationEnabled() family and anchors the class to the SelectQuery / InsertQuery / UpdateQuery / DeleteQuery query-type family. (Settled with ADmad in review.)

Scope

In: the entry point, the class, the factory seam, the soft deprecation, tests.
Out (deliberately, for follow-up if the shape lands): findList/findThreaded are hydration-neutral (key⇒value / nested tree regardless of hydration) — a docs note, not extra API; removing disableHydration() entirely (6.0); touching Database\Query\SelectQuery covariance (that is #19440's territory). Internal core call sites are intentionally not migrated — exists() and DatabaseSession::read() stay on find()->disableHydration() so foundational paths keep tolerating finders that override findAll() by returning a fresh query.

Review hardening

Went through several review passes (ADmad + an external pass). Net result: every attempt to make the subclass behaviorally stricter than disableHydration() (throwing on re-hydration, on fresh-query finders) broke ORM substitutability — most sharply, SelectLoader::_buildQuery() unconditionally calls enableHydration() on association queries, so a throw broke contain()/eager loading. Resolution: the subclass is now minimal and fully substitutable; strictness lives only at the opt-in public entry point.

Verification

• Full matrix green: testsuite on MySQL / MariaDB / Postgres / SQLite (PHP 8.2–8.5), Windows + SQL Server.
• Coding Standard & Static Analysis and Static Analysis for Split Packages green.
• Local: phpunit, phpstan, phpcs clean; the contain() eager-load interop and finder-guard paths covered by regression tests.

Related

• Narrow Table::find() to SelectQuery<TEntity> + make TSubject covariant #19440 — narrow Table::find() + TSubject covariance (the alternative direction this one makes optional)
• Propagate TEntity to find()/findOrCreate()/loadInto() and friends #19438 — Propagate TEntity to find()/findOrCreate()/loadInto()
• Type SelectQuery::first()/firstOrFail() via the TSubject template #19439 — Type SelectQuery::first()/firstOrFail() via TSubject
• 5.x: Add table entity generics #19388 — Add TEntity class template