[Zetazzz]

Superseded by #1881 on fix/graphile-readiness-disposal. Both PRs have identical base/head commits and diffs; review continues in #1881. The old branch is retained.

Graphile instances need explicit build readiness and reliable cleanup across cache entry generations. This Draft targets the complete readiness and generation-scoped disposal work described in #1747, developed incrementally with review before each next step.

The current implementation covers build readiness only. createGraphileInstance waits for schema construction, HTTP attachment, and Grafserv readiness before returning an entry or starting realtime. Success values use void; the upstream schema result object is explicitly adapted with Promise.resolve(pgl.getSchemaResult()).then(() => {}). Adapter, readiness, and release callbacks accept their actual synchronous or PromiseLike<void> returns.

Schema rejections are observed immediately. Failed builds wait for schema work to settle before releasing PostGraphile and the unique preset services. Cleanup attempts continue after individual release errors. A successful cleanup preserves the original build error; additional cleanup or reporting failures are aggregated with that error as the cause. This helper is limited to failed builds; external pool ownership, normal cache disposal, and realtime startup behavior remain unchanged.

The readiness coordinator, failed-build release helper, and ModuleConfigCache implementation live in src/utils. The package entry continues to export ModuleConfigCache and ModuleConfigCacheOptions. The former graphile-cache/module-config-cache subpath has been removed.

Generation-scoped disposal and drain, realtime subscription lifecycle changes, performance harness migration, and later memory/cache management are still pending. These lifecycle features are not implemented by the current diff and will be added only through subsequent review steps. The PR remains a Draft awaiting review of the current build-readiness increment.

The branch was independently based on main 735479ba289c73a1cafb3a7a3e38dfd9c9a9dda7. Current code validation on Node 24.19.0 / pnpm 10.34.5:

• graphile-cache: 3 suites / 27 tests passed, using mocks and deferred promises.
• CJS/ESM builds, both no-emit TypeScript checks, scoped ESLint, and git diff --check passed.
• Supply-chain policy and CI test-registration checks passed; graphile-cache is registered in the existing unit-test batch.
• Repository scans found no imports of the removed module-config-cache subpath; clean builds removed its CJS/ESM output.
• Existing warnings: ts-jest TS151002 and the unchanged package-wide lint warning for the unused unregister variable.

No database or real-service operations were used for local validation. The repository skips build/test CI jobs for Draft PRs; those skipped jobs are not a cloud validation pass.