Repository navigation
design(runtime): bind generated clients to explicit runtime instances #340
Description
Let a generated client hold an explicit runtime instance instead of consulting the global bridge registry for each call.
Use two clients for the same generated module, each bound to a different Python environment. Concurrent calls must remain independent.
The current module-level registry remains available as a convenience API. This proposal is related to #345 but is not part of its proof.
Acceptance criteria:
- Propose and independently review a small binding API before implementation.
- Prototype two clients from the same generated module, each holding a distinct RuntimeExecution instance.
- Interleaved and concurrent calls always use the bound instance without changing global registry state.
- Legacy registry-based imports continue to work.
- Bound calls use the same generated argument, conversion, and validation contract as legacy calls.
- Define ownership: disposing a client must not accidentally dispose a bridge shared by another client.
- Define development-reload behavior explicitly for bound and registry-based clients.
- Test mixed runtimes where supported, disposal, and failed calls without cross-client interference.
- Independent API review checks clarity, compatibility, and generated-code size.
Keep this design separate from transport pooling, Python object handles, and coroutine scheduling. It does not block the compiler and conversion prototypes.
Activity
[-]design(runtime): evaluate explicitly bound generated clients[/-][+]design(runtime): bind generated clients to explicit runtime instances[/+]bbopen commentedon Sep 20, 2026
The explicit runtime-binding design and prototype are complete. A companion
bindRuntime(runtime)returns{ api, dispose }; Python names remain underapi. Both bound and legacy output derive from the same compiled module and generator. Tests run two Python environments concurrently and cover mixed Node/HTTP runtimes, legacy registry behavior, reload, failures, and borrowed bridge ownership.Independent API review and generated-size measurements are recorded. Public generation of bound clients remains future work; this closes the bounded design issue.
Evidence:
docs/maintainers/client-binding-design.md,docs/maintainers/client-binding-prototype-review.md,test/client-binding-prototype.test.ts, anddocs/maintainers/architecture-decision-0.11.md.Verified release evidence:
0861ebeand mergef6f811dhave identical trees.The architecture decision records the accepted scope and prototype limits.
Closing as complete within the issue's bounded design scope.