API Stability
=============

``at-py`` is still a 0.x package. The current API is intended to be practical and
well tested, but not frozen.

Public Surface
--------------

The top-level ``at_py`` package is the curated application API. It exports
``ATClient``, common parsers and formatters, MAT helpers, runtime constants, and
selected result dataclasses.

The ``at_py.readwrite`` package exposes the full read/write surface, including
lower-level helpers and additional result types. Import from this namespace when
you need a symbol that is not intentionally re-exported at the package root.

Current Stabilization Decisions
-------------------------------

These choices are part of the current 0.x contract and should be changed only
with a changelog entry and focused tests:

* ``at_py`` remains the application namespace. It should include the runner
  client, common parse/read/format helpers, MAT helpers, runtime constants, and
  the result dataclasses needed by those helpers.
* ``at_py.readwrite`` remains the full implementation namespace. Lower-level
  helpers such as ``load_mat_normalized_path`` and ``parse_readvector_lines``
  stay there unless a concrete application use case justifies promoting them.
* Runtime parse and format APIs stay in-memory-first. Path-based convenience
  wrappers are limited to explicit helpers such as ``load_mat_normalized_path``;
  they are not added to every parser/formatter by default.
* Model dispatch follows Matlab ``read_env.m`` behavior. Writer-only aliases
  such as ``simplePE`` are not accepted by ``parse_read_env`` or
  ``format_parsed_env`` unless read-side behavior is implemented and tested.
* MAT v7.3 support stays demand-driven. Unsupported high-level MATLAB types
  should continue to fail loudly until an Acoustics Toolbox workflow needs them.

1.0 Exit Criteria
-----------------

Before a 1.0 release, maintainers should verify:

* the top-level ``at_py.__all__`` set is intentionally curated;
* result dataclasses used by top-level helpers are documented as public result
  contracts;
* runner-backed validation covers the primary application workflows;
* the release workflow can publish through PyPI Trusted Publishing;
* any breaking changes are either completed or explicitly deferred.

Current Compatibility Promise
-----------------------------

Within the 0.x line, prefer additive changes and clear deprecations where
possible. Breaking changes should be documented in the changelog and released as
minor bumps while ``major_version_zero = true`` remains configured for
Commitizen.