typebind 0.1.0a1__tar.gz

typebind-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.14.8

typebind-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing
+
+## Set up and run checks
+
+Fork the repository and create a branch from `main`. Install the uv version
+specified by `tool.uv.required-version` in [pyproject.toml](pyproject.toml), using
+[uv's installation instructions](https://docs.astral.sh/uv/getting-started/installation/).
+Do not relax that requirement to use a different local tool version.
+
+From the checkout root:
+
+```sh
+uv sync --locked
+uv run --no-sync poe check
+```
+
+uv installs the Python version selected by `.python-version` when needed. The
+root development group includes the two local plugin examples. No package-index
+credentials, publishing permissions or application secrets are needed.
+
+`poe check` runs formatting, lint, strict Pyright, tests, runnable examples,
+builds and isolated wheel verification. Run focused tasks while developing:
+
+```sh
+uv run --no-sync poe test
+uv run --no-sync pytest -m integration
+uv run --no-sync poe benchmark
+```
+
+See [Examples](examples/README.md) for individual example commands and what each
+script demonstrates.
+
+The test task reports branch coverage and missing lines as diagnostics; there is
+no percentage gate. The `integration` marker selects the installed-distribution
+test independently. It builds the two plugin wheels and the current library wheel,
+then verifies installation, version, exact local wheel origins and imports.
+It runs the discovery example against installed wheels, verifying real entry points,
+behavior results, nested JSON round trips and cross-package Pyright inference.
+Generic model and decorator wheel checks belong to artifact verification.
+
+The build creates the wheel from the sdist. Artifact verification checks package
+metadata with Twine, the packaged license and `py.typed`, and isolated runtime/typing
+behavior. The distribution directory must contain exactly one wheel and one sdist
+for the same release; use a clean output directory after changing versions.
+Installers follow wheel dependency metadata under lockfile-derived
+constraints; they do not preinstall undeclared dependencies. Isolated installs
+may access PyPI, so `poe check` is not an offline command. Runnable examples are
+usage acceptance checks; documentation prose is reviewed, not parsed by tests.
+
+Example packages belong to this checkout and must use its current source, not an
+independently selected typebind release. Their dependency metadata declares
+package relationships without version constraints. Root uv source configuration
+selects the local examples during development; the integration test installs the
+library and plugin wheels built from this checkout and verifies their installation
+origins. Changing the main package version does not require bumping the examples'
+own versions. Git retains the target `x.y.z` version; release preparation writes
+the full candidate version only into the CI working copy, as described in
+[Releasing](docs/releasing.md#prepare-and-check-a-candidate). Prerelease candidates
+use the same installation checks with their prepared version; the release workflow verifies the actual candidate rather than
+creating additional synthetic development and alpha versions in each test run.
+
+To check the minimum supported Python on POSIX shells, run
+`UV_PYTHON=3.12 uv sync --locked`, then `uv run --no-sync poe check`.
+On PowerShell set `$env:UV_PYTHON = "3.12"` before running `uv sync --locked`
+and `uv run --no-sync poe check`. CI checks Python 3.12–3.15 on Ubuntu 24.04. macOS and Windows are not part of
+the ongoing CI validation. The full matrix runs on PRs, main pushes, manual
+checks and the release workflow. Ordinary branch pushes do not trigger CI.
+Each job syncs dependencies once and runs the Poe sub-tasks as separate steps.
+
+A separate Python 3.12 job checks the minimum runtime dependencies declared in
+`pyproject.toml`. It keeps the locked development tools, resolves runtime
+constraints with `uv pip compile --resolution lowest-direct`, and installs that
+combination before running strict typing, non-integration tests and all examples.
+Artifact verification consumes the same constraints through `check-dist --constraint`,
+so its isolated wheel installation also exercises the minimum dependencies.
+The installed-plugin integration tests remain in the locked Python matrix; their
+own isolated environments use lockfile constraints.
+
+For workflow changes, run actionlint (the version is declared in `ci.yml`) and:
+
+```sh
+uv run --no-sync poe workflow-security
+```
+
+This runs offline zizmor checks. Validate orchestration with native tools and
+actual Actions runs; do not add library tests that mirror workflow YAML or step
+order. Exercise new project-owned automation behavior at its own boundary.
+
+## Measure performance changes
+
+Run `poe benchmark` for performance-related changes, or use
+`poe benchmark-models` and `poe benchmark-behavior` separately. Benchmarks are
+manual diagnostics, not a routine CI step or a timing gate.
+
+Model cases compare omitted and explicit tags, both public bases, multilevel
+families, Literal aliases and decorators against native Pydantic controls with
+matching frozen fields and default validation. A native identity-marking validator
+separates the cost of that guarantee from plain defaults. Copy cases isolate the
+identity guard cost; JSON cases exercise serialization, validation and nested
+`exclude_unset=True` round trips. Behavior cases compare table-based adaptation
+with direct implementation construction. These microbenchmarks do not establish
+service throughput; report the interpreter and comparison cases with results.
+
+## Submit a pull request
+
+Describe the concrete behavior changed, why it is needed, and the checks actually
+run. Include a small reproduction for bug fixes. Add tests for observable library
+behavior; keep configuration and documentation changes focused on their owners.
+Keep code, examples, comments and repository documentation in English.
+
+Call out public API, serialization, typing and compatibility changes. Preserve
+field definitions as the source of tags and keep discovery, assembly and runtime
+adaptation separate. The contracts and current limitations are in `docs/`.
+Benchmarks report measurements; they are not machine-dependent pass/fail gates.
+
+Keep credentials, private data, generated distributions and virtual environments
+out of commits. Report vulnerabilities through [the security policy](SECURITY.md),
+not public bug reports. External PRs run without publishing credentials. CI
+approval does not authorize publishing. Maintainers review and merge PRs; there
+is no automatic merge for dependency updates.
+
+## Environment and dependency maintenance
+
+The workflow files own runner labels. CI and publishing both use Ubuntu 24.04 (x64). Change OS
+versions explicitly in a reviewed PR and verify all affected jobs. Versioned
+labels avoid automatic OS-major migration; GitHub still updates the images and
+preinstalled tools. This is not a bit-for-bit frozen VM.
+
+The Python compatibility matrix intentionally follows current patch releases of
+3.12 through 3.15. Local development and publishing select `.python-version`.
+`pyproject.toml` fixes uv and the release build-backend constraint; `uv.lock`
+selects development and runtime dependencies. Third-party Actions use commit
+SHAs. actionlint has a fixed Go module version. Go, Git, shell utilities and the
+GitHub CLI are runner-provided tooling, deliberately updated with the image;
+they are not claimed to be pinned or covered by the Python lock audit.
+
+Actions Dependabot checks weekly. Minor/patch version updates share a PR; major
+updates remain separate. Security updates are not delayed by that version-update
+group. Review the diff and require the full CI checks before merging.
+
+Python Dependabot is not enabled yet: the inspected updater source
+uses uv 0.12.19, while this project's required uv is 0.13.0. This source inspection
+is not a successful hosted updater test. Keep the project pin; do not add a second
+lockfile or weaken the toolchain to accommodate a bot. Until a hosted updater can
+resolve the local example sources with the required uv, maintainers update Python
+dependencies in ordinary PRs:
+
+```sh
+uv lock --upgrade-package PACKAGE_NAME
+uv sync --locked
+uv run --no-sync poe check
+uv run --no-sync poe audit
+```
+
+For Pydantic updates, update `pydantic` and let its exact dependency select
+`pydantic-core`; typebind does not impose another core version constraint.
+Follow the [compatibility checks](docs/models.md#current-boundaries) for dependency
+changes. The locked matrix and minimum-dependency job cover their actual resolved
+combinations, not every version allowed by the package metadata.
+
+`poe audit` exports all locked third-party runtime/development entries to a
+temporary native `pylock.toml`, then uses pip-audit's lock reader with strict
+collection. The independent `Dependency audit` workflow runs weekly or manually.
+Vulnerabilities, collection failures and service errors fail that workflow and
+remain visible in Actions notifications; they are not suppressed. It is not a
+required PR check or a dependency of the publishing workflow. Maintainers triage
+findings for affected code paths and environments, and review new dependency risks
+when updating dependencies. A failed advisory query is not a vulnerability finding.
+An unresolved risk relevant to the release must be addressed before approving its
+upload; an unrelated development-dependency advisory is not an automatic release veto.
+The audit does not cover local project code, Actions, runner tools or the separate
+build-backend constraint. Review backend advisories when upgrading the toolchain.
+Security fixes still require review and tests; the audit does not update packages.
+Run it from Actions → Dependency audit → Run workflow, selecting `main`, or use
+`gh workflow run audit.yml --ref main`. The workflow must exist on the default
+branch for dispatch and scheduling. Inspect its first scheduled result and
+notification delivery on GitHub; local audit success does not establish either.
+
+Before enabling Python Dependabot, verify a real hosted update that changes a
+resolved dependency and passes CI with the required uv. A no-op lock rewrite is
+not that acceptance test. See [uv's Dependabot guide](https://docs.astral.sh/uv/guides/integration/dependabot/)
+and the [updater source](https://github.com/dependabot/dependabot-core/blob/780c17e16ac2cd5b8e04a9e27fc2da4de6043290/uv/Dockerfile).
+
+Publishing and one-time owner settings are described in [Releasing](docs/releasing.md).

typebind-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typebind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typebind-0.1.0a1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: typebind
+Version: 0.1.0a1
+Summary: Typed Pydantic model families, plugin discovery, and scoped behavior adapters.
+Keywords: pydantic,discriminator,generics,plugins,adapters
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.11.2,<3
+Requires-Dist: typing-extensions>=4.15
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/nicholas-1vbw/typebind
+Project-URL: Repository, https://github.com/nicholas-1vbw/typebind
+Project-URL: Issues, https://github.com/nicholas-1vbw/typebind/issues
+Description-Content-Type: text/markdown
+
+# typebind
+
+Build extensible Pydantic model families with automatic discriminator tags and
+statically typed fields. Bind behavior implementations to models without mixing
+them into the data classes. Select variants explicitly, or optionally discover
+models and implementations supplied by installed plugin packages.
+
+## Install
+
+Python 3.12 or later is required. This project is preparing its first release and
+has not been published to PyPI. From a local checkout:
+
+```sh
+python -m pip install .
+```
+
+The supported Pydantic range and other runtime requirements are declared in
+[pyproject.toml](https://github.com/nicholas-1vbw/typebind/blob/main/pyproject.toml).
+
+## Quick start
+
+Declare a family and its variants, then build an adapter for the variants you accept:
+
+```python
+from typebind import DiscriminatedModel, build_adapter, model
+
+
+@model(tag="kind")
+class Message(DiscriminatedModel):
+    identifier: str
+
+
+@model(variant="query")
+class Query(Message):
+    expression: str
+
+
+@model(variant="ping")
+class Ping(Message):
+    pass
+
+
+adapter = build_adapter(Message, variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`build_adapter` returns a native Pydantic `TypeAdapter`. For nested model fields,
+use [`bind_variants`](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#consumer-types).
+Import public APIs from `typebind`; underscore-prefixed modules are internal.
+
+The [`@model` decorator](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#decorator-declarations)
+preserves static checking for declared fields such as `identifier` and `expression`.
+Generated tag attributes such as `kind` are runtime-only: Pyright does not see
+them or accept them as constructor keywords. Use explicit generics when your
+code needs statically typed `Literal` tags:
+
+<details>
+<summary>Explicit generics with statically typed tags</summary>
+
+This standalone example provides the same validation and JSON round trip:
+
+```python
+from typing import Any, Literal
+
+from typebind import DiscriminatedModel, build_adapter, tag_field
+
+
+class Message[Kind: str](DiscriminatedModel):
+    kind: Kind = tag_field()
+    identifier: str
+
+
+class Query(Message[Literal["query"]]):
+    expression: str
+
+
+class Ping(Message[Literal["ping"]]):
+    pass
+
+
+adapter = build_adapter(Message[Any], variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`Message[Any]` keeps common fields typed while allowing runtime-selected tags;
+concrete variants retain their `Literal` tags. For example, `query.kind` has the
+static type `Literal["query"]`.
+
+</details>
+
+## Usage notes
+
+- Constructors can omit fixed tags, but incoming data routed through an adapter
+  must contain them. Keep tags in persisted JSON and bind the reader's accepted variants.
+- Ordinary dumps retain tags. If you need `exclude_unset=True`, use
+  `IdentityDiscriminatedModel` to retain omitted tags. Explicit tag exclusions and
+  `exclude_defaults=True` can still remove them; see the
+  [serialization contract](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#json-serialization-contract).
+- Strict Pyright is verified. Discriminator aliases, additional payload type
+  parameters and multiple model-family parents are unsupported; see
+  [typing and compatibility boundaries](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#current-boundaries).
+
+## Documentation and examples
+
+- [Runnable examples](https://github.com/nicholas-1vbw/typebind/blob/main/examples/README.md): setup and commands for model families, manual behavior assembly, decorators and cross-package discovery.
+- [Models](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md): declarations, nested binding, serialization and copying.
+- [Behaviors](https://github.com/nicholas-1vbw/typebind/blob/main/docs/behaviors.md): typed interfaces, assembly and dispatch contracts.
+- [Discovery](https://github.com/nicholas-1vbw/typebind/blob/main/docs/discovery.md): package layout, entry points and scoped selection. Discovery is optional for all model and behavior APIs.
+
+## Contributing
+
+See [Contributing](https://github.com/nicholas-1vbw/typebind/blob/main/CONTRIBUTING.md)
+for development setup and checks, and
+[Releasing](https://github.com/nicholas-1vbw/typebind/blob/main/docs/releasing.md)
+for publishing. Report vulnerabilities through the
+[security policy](https://github.com/nicholas-1vbw/typebind/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/nicholas-1vbw/typebind/blob/main/LICENSE).

typebind-0.1.0a1/README.md

@@ -0,0 +1,128 @@
+# typebind
+
+Build extensible Pydantic model families with automatic discriminator tags and
+statically typed fields. Bind behavior implementations to models without mixing
+them into the data classes. Select variants explicitly, or optionally discover
+models and implementations supplied by installed plugin packages.
+
+## Install
+
+Python 3.12 or later is required. This project is preparing its first release and
+has not been published to PyPI. From a local checkout:
+
+```sh
+python -m pip install .
+```
+
+The supported Pydantic range and other runtime requirements are declared in
+[pyproject.toml](https://github.com/nicholas-1vbw/typebind/blob/main/pyproject.toml).
+
+## Quick start
+
+Declare a family and its variants, then build an adapter for the variants you accept:
+
+```python
+from typebind import DiscriminatedModel, build_adapter, model
+
+
+@model(tag="kind")
+class Message(DiscriminatedModel):
+    identifier: str
+
+
+@model(variant="query")
+class Query(Message):
+    expression: str
+
+
+@model(variant="ping")
+class Ping(Message):
+    pass
+
+
+adapter = build_adapter(Message, variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`build_adapter` returns a native Pydantic `TypeAdapter`. For nested model fields,
+use [`bind_variants`](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#consumer-types).
+Import public APIs from `typebind`; underscore-prefixed modules are internal.
+
+The [`@model` decorator](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#decorator-declarations)
+preserves static checking for declared fields such as `identifier` and `expression`.
+Generated tag attributes such as `kind` are runtime-only: Pyright does not see
+them or accept them as constructor keywords. Use explicit generics when your
+code needs statically typed `Literal` tags:
+
+<details>
+<summary>Explicit generics with statically typed tags</summary>
+
+This standalone example provides the same validation and JSON round trip:
+
+```python
+from typing import Any, Literal
+
+from typebind import DiscriminatedModel, build_adapter, tag_field
+
+
+class Message[Kind: str](DiscriminatedModel):
+    kind: Kind = tag_field()
+    identifier: str
+
+
+class Query(Message[Literal["query"]]):
+    expression: str
+
+
+class Ping(Message[Literal["ping"]]):
+    pass
+
+
+adapter = build_adapter(Message[Any], variants=(Query, Ping))
+query = Query(identifier="q", expression="hello")  # kind defaults to "query"
+wire = adapter.dump_json(query)
+assert adapter.validate_json(wire) == query
+assert type(adapter.validate_python({"kind": "ping", "identifier": "p"})) is Ping
+print(wire.decode())  # {"kind":"query","identifier":"q","expression":"hello"}
+```
+
+`Message[Any]` keeps common fields typed while allowing runtime-selected tags;
+concrete variants retain their `Literal` tags. For example, `query.kind` has the
+static type `Literal["query"]`.
+
+</details>
+
+## Usage notes
+
+- Constructors can omit fixed tags, but incoming data routed through an adapter
+  must contain them. Keep tags in persisted JSON and bind the reader's accepted variants.
+- Ordinary dumps retain tags. If you need `exclude_unset=True`, use
+  `IdentityDiscriminatedModel` to retain omitted tags. Explicit tag exclusions and
+  `exclude_defaults=True` can still remove them; see the
+  [serialization contract](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#json-serialization-contract).
+- Strict Pyright is verified. Discriminator aliases, additional payload type
+  parameters and multiple model-family parents are unsupported; see
+  [typing and compatibility boundaries](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md#current-boundaries).
+
+## Documentation and examples
+
+- [Runnable examples](https://github.com/nicholas-1vbw/typebind/blob/main/examples/README.md): setup and commands for model families, manual behavior assembly, decorators and cross-package discovery.
+- [Models](https://github.com/nicholas-1vbw/typebind/blob/main/docs/models.md): declarations, nested binding, serialization and copying.
+- [Behaviors](https://github.com/nicholas-1vbw/typebind/blob/main/docs/behaviors.md): typed interfaces, assembly and dispatch contracts.
+- [Discovery](https://github.com/nicholas-1vbw/typebind/blob/main/docs/discovery.md): package layout, entry points and scoped selection. Discovery is optional for all model and behavior APIs.
+
+## Contributing
+
+See [Contributing](https://github.com/nicholas-1vbw/typebind/blob/main/CONTRIBUTING.md)
+for development setup and checks, and
+[Releasing](https://github.com/nicholas-1vbw/typebind/blob/main/docs/releasing.md)
+for publishing. Report vulnerabilities through the
+[security policy](https://github.com/nicholas-1vbw/typebind/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/nicholas-1vbw/typebind/blob/main/LICENSE).

typebind-0.1.0a1/SECURITY.md

@@ -0,0 +1,39 @@
+# Security policy
+
+## Report a vulnerability privately
+
+Use [Report a vulnerability](https://github.com/nicholas-1vbw/typebind/security/advisories/new)
+on the repository's Security tab. Include the affected version, a minimal
+reproduction, expected and actual behavior, and the impact. Remove credentials
+and private data from examples. Do not publish exploit details in an issue or PR
+before coordinating disclosure with the maintainer.
+
+This channel requires the owner to enable GitHub private vulnerability reporting
+when the repository becomes public. If the button is unavailable, open an issue
+asking for a private reporting channel without including vulnerability details.
+No response-time or remediation SLA is promised.
+
+## Supported releases
+
+Before the first stable release, fixes target the latest published prerelease.
+After a stable release, fixes target the latest release; upgrading may be
+necessary. Older release branches do not have a separate backport commitment.
+Report suspected problems even if you cannot yet reproduce them on that version.
+
+## Trust boundaries
+
+Typebind parses model data using Pydantic and assembles explicitly selected model
+and behavior classes. Discriminator tags identify branches; they do not authorize
+a caller. Applications own authentication, authorization, input size limits and
+resource budgets.
+
+Entry point loading imports and executes installed Python packages. Behavior
+implementations are also trusted executable code. Family checks and source
+scopes are not a sandbox, and post-import selection cannot undo import side
+effects. Install only plugins you trust. Reports of bypassed selection, incorrect
+branch validation or other unexpected behavior remain welcome; these boundaries
+do not exempt defects in the library from investigation.
+
+The persistence contract is Pydantic JSON round trips. Pickle is not a supported
+interchange format. Dependency alerts and audits detect known dependency issues;
+they do not replace reports about typebind itself or a security review.

typebind-0.1.0a1/benchmarks/behavior.py

@@ -0,0 +1,90 @@
+"""Warm single-process microbenchmark, not a service throughput/load test."""
+
+import gc
+import json
+import platform
+import sys
+from abc import abstractmethod
+from statistics import median
+from timeit import Timer
+from typing import Any, Literal, Protocol, get_type_hints
+
+from typebind import DiscriminatedModel, Implementation, assemble, tag_field
+
+
+class Message[Kind: str](DiscriminatedModel):
+    kind: Kind = tag_field()
+    text: str
+
+
+class Query(Message[Literal["query"]]):
+    pass
+
+
+class Describable(Protocol):
+    @property
+    @abstractmethod
+    def model(self) -> Message[Any]: ...
+
+    @abstractmethod
+    def describe(self) -> str: ...
+
+
+class QueryObject(Implementation[Query], Describable):
+    def describe(self) -> str:
+        return self.model.text
+
+
+runtime = assemble(
+    variants=[Query], implementations=[QueryObject], required_interfaces=[Describable]
+)
+query = Query(text="hello")
+view = runtime.adapt(query, Describable)
+
+
+def direct(model: Query) -> str:
+    return model.text
+
+
+def reflecting_call() -> str:
+    """Comparison only: simulate repeated family annotation resolution."""
+    member = vars(Describable)["model"]
+    get_type_hints(member.fget)
+    return runtime.adapt(query, Describable).describe()
+
+
+cases = {
+    "direct_function": "direct(query)",
+    "reuse_adapter": "view.describe()",
+    "known_constructor_and_call": "QueryObject(query).describe()",
+    "adapt_and_call": "runtime.adapt(query, Describable).describe()",
+    "reflection_and_adapt_and_call": "reflecting_call()",
+}
+assert direct(query) == view.describe() == reflecting_call() == "hello"
+results: dict[str, object] = {}
+for name, statement in cases.items():
+    timer = Timer(statement, setup="gc.enable()", globals=globals())
+    timer.timeit(number=1_000)
+    samples = [elapsed / 100_000 * 1e6 for elapsed in timer.repeat(repeat=7, number=100_000)]
+    results[name] = {
+        "minimum_us": min(samples),
+        "median_us": median(samples),
+        "samples_us": samples,
+    }
+print(
+    json.dumps(
+        {
+            "python": sys.version,
+            "platform": platform.platform(),
+            "gc_enabled": gc.isenabled(),
+            "iterations": 100_000,
+            "repeats": 7,
+            "scope": (
+                "Sequential warm calls on an existing model; excludes discovery, "
+                "assembly, parsing, I/O and concurrency."
+            ),
+            "results": results,
+        },
+        indent=2,
+    )
+)