TypedPython: run the type gate when a module is imported (development mode)

Maintainer decision 2026-10-04 (agent-first): type errors must stop code before it runs, not only in the build.

(a) The gate as a default Gradle build step: TypedPython 1b: run the gate as a default Gradle build step #20 (unchanged).
(b) New: in development mode (notebook cells, hot reload, a debug app run), importing a project module runs the same gate (N-7) on it first; a type error stops the import with an error that lists the diagnostics. Release builds rely on (a) and skip it. Results are cached by file content hash so an unchanged module is not re-checked.
Not done: per-call runtime argument checks, because compiled and interpreted code must behave exactly as CPython does.
Completion: SPEC N-7 entry for (b); a test that imports a module with a type error in development mode and gets the error before any of its code runs (red first), and that the same module imports in release mode; a cache hit test.

Agreed plan (leader, 2026-10-04):

This comes before TypedPython 1b: run the gate as a default Gradle build step #20, because both share the same python -m typedpython check, file-hash cache and diagnostic format.
Form: an import hook (meta path finder) installed only in development mode. It checks modules under the project source roots, and a type error raises an ImportError carrying the diagnostics. It is not installed in release builds.
Known cost: the first import of a module pays one gate run, a few hundred ms (Pyrefly's fixed cost). Later imports of unchanged files hit the hash cache. Reducing that first-import delay is tracked together with TypedPython gate: cut the type-report overhead #21.

Landed in develop via the import-gate PR. Follow-ups: on-disk cache, startup wiring.

Navigation Menu