Polyglot Tooling and Observability
==================================

The Python package is the reference implementation, but the project now ships
release contracts for several language bindings. This page records the
developer-facing expectations that keep those bindings aligned.

Tooling parity
--------------

The Python reference package keeps the language-specific tools that have a
clear local benefit:

* ``scalene`` is kept for Python-only profiling.
* ``mutmut`` is kept for Python-only mutation testing.
* ``pytest-benchmark`` is kept for Python performance regression checks.
* ``ruff`` and ``ty`` remain the Python lint and type gates.

Those tools are not forced onto the non-Python bindings. The equivalent gates
for the other package ecosystems are the native build, lint, test, packaging,
and conformance checks documented in the release matrix:

* TypeScript: ``npm run check`` and ``npm pack --dry-run``
* Go: ``go test`` and ``go vet``
* Rust: ``cargo fmt``, ``cargo clippy``, ``cargo test``, ``cargo package``
* Julia: ``Pkg.test``
* .NET 11: ``dotnet build``, ``dotnet test``, ``dotnet pack``
* R: ``R CMD build`` and ``R CMD check --as-cran``

The release matrix in `docs/release/polyglot-bindings.md` describes the
package-manager targets and tag conventions that go with those gates.

The canonical version source and the manifest lockstep rule are documented in
`docs/developer_guide/versioning_and_release_policy.rst`. Use that policy page
when changing any release-manifest version.

Versioning contract
-------------------

Each binding follows the release conventions of its own ecosystem:

* Python tags trigger PyPI/TestPyPI publication, while the conda-forge recipe
  is updated separately through the feedstock flow.
* TypeScript uses ``typescript-v*`` tags and publishes to npm with provenance.
* Go uses ``bindings/go/v*`` tags that line up with the module proxy rules.
* Rust uses ``rust-v*`` tags and publishes to crates.io.
* Julia uses ``julia-v*`` tags with TagBot sync and the General registry.
* .NET uses ``dotnet-v*`` tags and publishes ``net11.0`` packages to NuGet.
* R uses ``r-v*`` tags and publishes source artifacts through GitHub Releases,
  with CRAN or r-universe still handled externally.

Logging policy
--------------

Library code should stay quiet by default. The CLI is the only surface that is
expected to emit user-facing status output, and even there the output must stay
stable for scripting.

The current policy is:

* ``--quiet`` suppresses status chatter.
* ``--format json`` and ``--format csv`` are the machine-readable output modes.
* Debug or verbose detail must remain opt-in and must not change stdout
  payloads that users rely on for automation.

When a binding does not have a direct equivalent for a Python-only tool, the
fallback is to keep the gap explicit rather than invent a weak substitute.
That keeps the quality gates honest and makes the release contract easier to
audit across languages.