# Roadmap to AudioSamples v1.0.0

The `audio_samples` crate is already functionally extensive and architecturally mature, with strong guarantees around sample typing, zero-allocation patterns, trait-based composition, and modularity. The path to **1.0.0** is therefore not about adding major new functionality, but about **stability, polish, internal coherence, and long-term API guarantees**.

Below is a focused roadmap from the current **v0.9.0** to a stable and semver-protected **v1.0.0**.

---

<!-- ## **0.9.x — Stabilisation and Internal Review**

This cycle is about tightening the internal structure without breaking public APIs prematurely.

### Goals

* Conduct a full audit of modules (`operations`, `traits`, `repr`, etc.)
* Identify naming inconsistencies, unclear method boundaries, redundant methods, or missing symmetry
* Review error variants, message consistency, and ergonomic patterns
* Confirm that trait bounds across modules reflect actual API contracts
* Internal review of iterator guarantees, window behaviour, padding semantics
* Settle final conventions for mono/multi distinction: naming, borrowing, ownership

### Expected Outputs

* A list of intended breaking changes
* A list of internal inconsistencies to be resolved
* Light refactoring that is still backward-compatible

Once this is complete, the **intended 1.0 surface is known**, even if not yet implemented.

---

## **0.10.0 — Error System Redesign**

The error layer is the weakest remaining subsystem. A complete revamp is required before 1.0.

### Goals

* Replace the current monolithic `AudioSampleError` with a **small, well-defined hierarchy**
* Enforce consistent error naming, formatting, and contextual data
* Split conversion errors, range violations, layout mismatches, and configuration errors into separate types
* Ensure operations all use the correct error types, not generic string-based variants
* Provide a stable `AudioSampleResult<T>` alias
* Achieve predictable, inspectable error behaviour across all operations

### Rationale

A clean error system is essential for ecosystem integration, especially for the CLI, Python bindings, and documentation.

--- -->

## **0.11.0 — API Consistency Pass**

This release resolves all inconsistencies identified in 0.9.x and aligns the API around a coherent design philosophy.

### Goals

* Finalise naming for:
  `as_type`, `to_type`, `cast_as`, `cast_to`, and all derived helpers
* Ensure every operation has a clear allocation policy (documented)
* Audit builder APIs (e.g., `processing()`) for consistency:
  *ordering, naming, default behaviour, error semantics*
* Harmonise mono/multi behaviour
* Ensure that trait-based operations across modules have consistent method names and signatures
* Introduce deprecation warnings for anything to be removed in 1.0

### Rationale

At this stage, the API surface is essentially frozen. All breaking changes must happen *here*.

---

## **0.12.0 — Documentation and Contracts Release**

Once the API is stable, the next step is to articulate the guarantees it provides.

### Goals

* Fully document:

  * lifetime semantics and borrowed/owned behaviour
  * allocation guarantees of every operation
  * trait designs and their precise roles
  * iterator stability and padding semantics
  * distinctions between audio-aware conversions vs. raw casting
  * invariants of `AudioSamples`, `MonoData`, `MultiData`
* Write architectural guides for:

  * trait-based operation layering
  * sample type system
  * conversion pipeline
  * processing builder
  * iterator design
* Provide “How to think about this crate” documentation
* Expand examples demonstrating the complete ecosystem

### Rationale

A 1.0 crate must be self-teaching. This release establishes the normative documentation that defines the crate’s philosophy and constraints.

---

## **0.13.0 — Performance Validation and Micro-Optimisation**

Before 1.0, the performance floor should be validated and locking in.

### Goals

* Benchmark every core operation: conversions, iterators, windows, transforms, statistics
* Validate no accidental regressions occurred during API clean-ups
* Confirm SIMD behaviour for conversion and arithmetic heavy paths
* Validate that borrowed/owned transitions do not cause accidental allocations
* Micro-optimise pathological cases identified in testing

### Rationale

Performance cannot be retrofitted after 1.0. This ensures all guarantees are real rather than implied.

---

## **0.14.0 — Final Hardening Pass**

The last pre-1.0 release. Conservative, stability-focused, with no new features.

### Goals

* Resolve all outstanding deprecations
* Run full suite of stress tests (especially windowing, STFT/ISTFT, resampling, dynamic range ops)
* Improve internal invariants checking
* Validate cross-platform behaviour
* Validate thread safety, Send/Sync guarantees

### Rationale

After this release, the API must not change in any breaking way.

---

## **1.0.0 — Stable Release**

The crate is now stable, semver-locked, and production-ready.

### Guarantees

* **Stable API surface**
* **Well-defined error system**
* **Documented allocation behaviour**
* **Zero-copy and zero-allocation guarantees where promised**
* **Consistent naming, signatures, and patterns across all operations**
* **Predictable, stable iterators and windows**
* **Robust trait boundaries and feature-gated modularity**
* **Clear and complete documentation**

### Summary

No new major features are introduced at 1.0. Instead, 1.0 marks the point at which users can depend on `audio_samples` with confidence that the design is intentional, complete, and stable.
