Update Python API to avoid private types in public signatures

[ScottCarda-MS]

Fix private API leakage in the qdk Python package

Problem

Several internal types from private modules (e.g. qdk._native, qdk._types, qdk.qre._application) were leaking through public function signatures—return types, parameter types, and TypeVar constraints. This caused:

• Type checker warnings: pyright/mypy flag qdk._native.Output as a private-module access when users annotate variables holding values from public functions.
• Broken doc cross-references: py2docfx and Sphinx can't generate links for types that have no public import path.
• Unintentional API coupling: users who follow IDE "go to definition" land in private modules and start depending on undocumented internals.

Solution

1. qdk.internal and qdk.qre.internal modules

New modules that re-export internal types used in public signatures. These are explicitly labeled as unsupported—they exist only so type checkers can resolve annotations and doc generators can produce links. Users are warned not to depend on them.

Each module uses a TYPE_CHECKING guard to provide minimal Protocol definitions at type-check time (limiting the visible surface) while re-exporting the real classes at runtime (preserving identity checks and zero-cost pass-through).

qdk.internal exposes: StateDumpData, Circuit, Closure, GlobalCallable, Output, Config, QirInputData, Zone, ZoneType

qdk.qre.internal exposes: ApplicationContext, DataclassProtocol, Instruction, InstructionSourceNodeReference

2. Annotation fixes for ISA enumeration nodes

Three ISAQuery methods returned private subtypes in their annotations:

• __add__ → _SumNode (now ISAQuery)
• __mul__ → _ProductNode (now ISAQuery)
• bind() → _BindingNode (now ISAQuery)

All three subtypes inherit from ISAQuery and users only interact through the ISAQuery interface. Widening the return annotation to the public base class eliminates the leakage with no change in runtime behavior.

3. _Context → ApplicationContext rename

The private _Context class in qdk.qre._application appeared in two public signatures: Application.context() (return type) and TraceQuery.enumerate() (parameter type). Users couldn't annotate variables holding the context. Renamed to ApplicationContext (non-private name) and routed through qdk.qre.internal.

4. check_api_surface.py lint script

New CI-ready lint that detects private-symbol leakage in the public API surface:

• Walks all public modules' __all__ exports
• Inspects function/method type annotations for references to types defined in private (_-prefixed) modules
• Excludes types that are publicly re-exported (defined in private module but listed in a public __all__)
• Groups output by private type for actionable diagnosis
• Supports --json for machine-readable output
• Integrated into build.py: runs automatically after qdk build when --check is enabled (the default); skipped with --no-check

Files changed

File	Change
source/qdk_package/check_api_surface.py	New — lint script
build.py	Added API surface check after qdk build (gated on --check)
source/qdk_package/qdk/internal.py	New — qdk.internal re-export module
source/qdk_package/qdk/qre/internal.py	New — qdk.qre.internal re-export module
source/qdk_package/qdk/qre/__init__.py	Added TraceParameters to __all__
source/qdk_package/qdk/qre/_application.py	Renamed _Context → ApplicationContext
source/qdk_package/qdk/qre/_instruction.py	Widened bind() return type to ISAQuery
source/qdk_package/qdk/qre/_isa_enumeration.py	Widened __add__, __mul__, bind return types to ISAQuery
source/qdk_package/qdk/qre/_trace.py	Updated _Context → ApplicationContext in type hints
source/qdk_package/qdk/_context.py	Improved noise parameter docstring
source/qdk_package/qdk/_interpreter.py	Improved noise parameter docstring

Validation

• check_api_surface.py reports 0 violations against the current codebase.
• Jupyter notebook experience verified (Config MIME bundles, Output display, StateDumpData via save_events).
• All changes are annotation/re-export only — no runtime behavior changes.