driver-lang 1.0.0

# driver-lang v1.0.0 — API Freeze

**The surface is stable.** v0.2.0 delivered the driver — a [`Session`](../API.md#session), a [`Stage`](../API.md#stage) trait, and a type-checked [`Pipeline`](../API.md#pipeline); v1.0.0 freezes them. Everything the crate exposes — the five types, their methods, the run-order and error-counting behaviors, the trait implementations, and the `std` / `serde` feature flags — is now stable under Semantic Versioning and will not change in a breaking way within the `1.x` series. No functional changes from 0.2.0; this release records the promise.

## What is driver-lang?

The driver that ties a compiler's phases into one run. A compiler is a sequence of phases — lex, parse, resolve names, check types, lower, emit — each taking the previous phase's artifact and producing the next. driver-lang carries the shared configuration and diagnostics from the first phase to the last, threads each artifact into the next phase, and stops cleanly when a phase fails. It owns no phases and wires no first-party dependency; a language plugs its own lexer, parser, and backend in as stages. `no_std` (needs only `alloc`), no `unsafe` (`#![forbid(unsafe_code)]`).

## The frozen surface

The whole public API, and all of it is stable as of 1.0.0:

- **[`Session<C>`](../API.md#session)** — the ambient state of one run.
  - **Config:** `new`, `config`, `config_mut`, `into_config`.
  - **Diagnostics:** `emit`, `error`, `warn`, `note`, `diagnostics`, `take_diagnostics`.
  - **Checkpoints:** `error_count`, `has_errors`, `abort_if_errors`.
- **[`Stage<C>`](../API.md#stage)** — one phase: `Input`, `Output`, `name`, `run`.
- **[`Pipeline<C, S>`](../API.md#pipeline)** — stages composed: `new`, `then`, `run`, `name`; with the [`Then<A, B>`](../API.md#then-type) composition node.
- **[`Diagnostic`](../API.md#diagnostic)** / **[`Severity`](../API.md#severity)** — one message and its seriousness (`Error` / `Warning` / `Note`).
- **[`DriverError`](../API.md#drivererror)** — the failure that halts a run.
- **Features:** `std` (default) and `serde`.

## The SemVer promise

- Nothing in the frozen surface is removed or changed in a breaking way within `1.x`. A breaking change means a new major version.
- `1.x` releases may **add** to the surface (new methods, new trait impls, new feature-gated helpers) without breaking existing code.
- Two behaviors are part of the contract, not just today's implementation: a pipeline runs its stages left to right and stops at the first [`DriverError`](../API.md#drivererror); and only [`Severity::Error`](../API.md#severity) counts toward [`error_count`](../API.md#error_count) and [`abort_if_errors`](../API.md#abort_if_errors). A `1.x` release will not change either except to fix a documented bug.
- The private fields behind the types are not part of the surface; they may change freely.
- MSRV (Rust 1.85) is a compatibility surface: a raise is a minor, documented change, never a patch.

`docs/API.md` carries the same promise inline, per public item.

## Why freeze now

The surface is deliberately small — five types, one generic pipeline, no dependencies but optional `serde` — and it has not needed to grow. The shape is the one a real compiler driver takes: a session of shared state, phases as typed transforms, and a pipeline that sequences them. The awkward cases are handled and tested: a stage that emits errors and keeps going versus one that aborts, error attribution to the innermost failing stage in a nested chain, diagnostics that survive a later failure, and the `no_std` build. The advanced pieces a future consumer might want — a functional-closure stage adapter, a run trace of which stages executed, richer diagnostic metadata — are all non-breaking `1.x` additions. There is nothing speculative left to design, so there is nothing to gain by staying pre-1.0.

## Performance

Unchanged from 0.2.0 — a pipeline is a single monomorphized type, so driving it is as cheap as calling the stages by hand, and the session's error tally is maintained incrementally. Latest local Criterion means (`cargo bench --bench bench`, Linux x86_64 / WSL2, Rust stable, release build):

| Workload | Time |
|----------|-----:|
| `Double → Increment → Sum` pipeline, 16 elements | ~15 ns |
| `Double → Increment → Sum` pipeline, 256 elements | ~100 ns |
| `Double → Increment → Sum` pipeline, 4096 elements | ~1.16 µs |
| Emit 128 diagnostics into a session | ~261 ns |

Numbers vary by CPU and environment; run the suite on your target to establish a baseline.

## Breaking changes

**None.** The 1.0.0 surface is identical to 0.2.0; this release only promises stability.

## Verification

Run on Windows x86_64, with testing on Linux (WSL2 Ubuntu), Rust stable and the 1.85 MSRV; the same commands run in the CI matrix across Linux, macOS, and Windows:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --lib -- -D warnings
cargo test
cargo test --all-features
cargo test --no-default-features --lib
cargo build --no-default-features --lib
cargo run --example calculator
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
```

All green. Counts at this tag:

- Default features: 37 unit + 5 integration + 3 property + 30 doctests.
- `--no-default-features` (lib): 37 unit (the crate is `no_std` + `alloc`).

## Installation

```toml
[dependencies]
driver-lang = "1"

# no_std:
driver-lang = { version = "1", default-features = false }

# with serde derives on Severity and Diagnostic:
driver-lang = { version = "1", features = ["serde"] }
```

MSRV: Rust 1.85 (2024 edition).

## Documentation

- [README](https://github.com/jamesgober/driver-lang/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/driver-lang/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/driver-lang/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.2.0...v1.0.0`](https://github.com/jamesgober/driver-lang/compare/v0.2.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/driver-lang/blob/main/CHANGELOG.md#100---2026-07-07).