# AI implementation contract (normative)

This is a machine-oriented engineering contract, not a replacement for the human README. The Japanese `AGENTS.md` is authoritative. Do not redesign the system from inference.

- One shared `DeviceProxy` is **only** a factory: map a unique device-class name to a registered callable `creator`. No transport abstraction, backend registry, automatic discovery, entry points, or device database.
- The HTTP (`ese774_frame`), gRPC (`grpc_frame`), and Tango (`tango_frame`) packages remain independent. This package imports none of them at runtime.
- Device packages own their **dedicated client classes** and their `.pyi` signatures. Client-side overrides and additions must be reflected in those dedicated stubs; never substitute a generic base client's stub.
- HTTP/gRPC may have separate sync and async dedicated clients. `make_async_sync_factory` selects between them; the shared `DeviceProxy` does not interpret `async_mode`. Tango is not forced into this pair model.
- Constructor arguments, `config`, `api_spec`, and connection details belong to the device/framework. The shared factory forwards them unchanged.
- A device package may expose direct clients, its own `DeviceProxy`, and the shared `DeviceProxy`. These options coexist; their registries are not automatically merged.
- Registration must be explicit Python execution. Import-time registration is optional, not mandatory. Duplicate device-class names are rejected.
- For common `DeviceProxy` typing, maintain an **explicit** JSON map from device-class names to the **fully qualified dedicated client classes**. Run `typing_generator` to generate `src/device_proxy_factory/core.pyi`. The generator only imports class names in the stub; it does not copy or regenerate client API declarations.
- Python type checkers do not automatically merge overloads from different packages. Updating `core.pyi` and rebuilding/reinstalling the common package is required when the set of typed devices changes. Installed client packages must be available for type resolution. This is a known limitation, not a feature to conceal.
- Preserve Python 3.7 support and Japanese code comments. Never invent actual class names. Review the real HTTP/gRPC/Tango sources and existing stub generators before modifications.
- Validate runtime multi-device operation, duplicate registration, argument forwarding, and static resolution of overridden client methods. Keep README and Japanese/English Pages in sync.