# arena-lang v0.1.0 — Scaffold

**The repository bootstrap.** v0.1.0 stands up the crate, the tooling, and the
quality gates the implementation is built on — and nothing more. There is no
domain logic in this release on purpose: the typed arena, the stable node
handles, capacity bounds, and the contiguous chunk store land across the 0.x
series, each behind a passing gate. This tag exists so that the first line of
real allocator code is written against a green CI, a fixed toolchain contract,
and a documented plan, rather than into an empty directory.

## What is arena-lang?

A typed bump allocator for compiler tree nodes. It hands out a node's storage
from a contiguous chunk, returns a stable handle that never moves for the life
of the arena, and frees everything at once when the arena is dropped. It is the
allocation substrate beneath `ast-lang` and the IR: nodes are allocated forward,
their addresses stay put as the arena grows, and there is no per-node
deallocation to track. It owns arena allocation and stable addressing only —
tree shape is `ast-lang`, traversal is the passes above it — and it is one of the
foundation crates of the `-lang` language-construction family.

## What's in 0.1.0

### Crate manifest and toolchain contract

`Cargo.toml` declares the full publish metadata — description, keywords,
categories, repository, homepage, dual `Apache-2.0 OR MIT` license, and authors —
on Rust 2024 edition with MSRV 1.85. The feature set is minimal and additive:
`std` on by default, with an opt-in `serde` feature reserved for serialising node
metadata later. No first-party dependency is wired yet; the underlying chunk
store is added when the allocator code first uses it, so the scaffold carries no
unused dependency.

### Quality gates, wired before the code

The CI matrix (`.github/workflows/ci.yml`) runs the full gate on Linux, macOS,
and Windows against both stable and the 1.85 MSRV: `cargo fmt --check`, clippy on
default and all features with `-D warnings`, the test suite on both feature sets,
and a documentation build with `-D warnings`. A separate security job runs
`cargo audit` and `cargo deny check`. `deny.toml`, `clippy.toml`, and
`rustfmt.toml` pin the license allow-list, the lint profile (MSRV-aligned to
1.85), and the import-grouping style. The crate root sets `#![forbid(unsafe_code)]`
and `#![deny(missing_docs)]` from the first commit.

### Documentation and plan

`README.md` and `docs/API.md` describe the intended surface and mark each item
still planned, so the public contract is legible before it is implemented.
`dev/DIRECTIVES.md` records the definition of done and the project-specific
invariants the property tests will hold to: a handle resolves to the same node
for the life of the arena; growth never moves or invalidates an issued handle;
distinct allocations never alias; `get(alloc(n)) == &n` round-trips; capacity
exhaustion is a defined error, never a silent wrap or a panic. `dev/ROADMAP.md`
front-loads the hard part — the typed-arena layer giving `ast-lang` stable,
non-moving node addresses at v0.2.0, where the chunk store is also wired — and
carries an anti-deferral rule: no listed hard task slips to a later phase without
the file recording the move and the reason.

## Breaking changes

**None.** This is the first tag.

## Verification

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo +1.85 build --all-features
cargo audit
cargo deny check
```

Counts at this tag: 1 unit test (a build smoke test), 0 doctests — there is no
public surface to exercise yet.

## What's next

- **0.2.0 — Typed arena (the hard part, not deferred).** Build the typed bump
  allocator over a contiguous chunk store: forward node allocation, stable `Copy`
  handles that survive growth, and bounded capacity with a defined exhaustion
  error. Handle stability, non-aliasing, and `alloc`/`get` round-trip come under
  property tests against a `Vec`-backed reference arena.

## Installation

```toml
[dependencies]
arena-lang = "0.1"
```

MSRV: Rust 1.85.

## Documentation

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

---

**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/arena-lang/blob/main/CHANGELOG.md).
