Match remade-with-rust portfolio conventions: hyphenated crate names, Mata Network homepage, portfolio README structure

Author: tim-almond-house

Cargo.toml

@@ -18,9 +18,9 @@ version = "0.1.0-alpha.1"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/remade-with-rust/rusty_alloc"
-# Part of the remade-with-rust portfolio — the org page is the front door, so
-# every crate points at it rather than only at its own repo.
-homepage = "https://github.com/remade-with-rust"
+# Portfolio convention (matches rusty_h264): homepage is Mata Network, the
+# parent org, not the GitHub org.
+homepage = "https://www.mata.network/"
 authors = ["remade-with-rust"]
 keywords = ["allocator", "malloc", "mimalloc", "memory", "no-std"]
 categories = ["memory-management", "no-std", "development-tools"]

README.md

@@ -1,124 +1,189 @@
+[![crates.io](https://img.shields.io/crates/v/rusty_alloc.svg)](https://crates.io/crates/rusty_alloc)
+[![docs.rs](https://img.shields.io/docsrs/rusty_alloc)](https://docs.rs/rusty_alloc)
+[![CI](https://github.com/remade-with-rust/rusty_alloc/actions/workflows/ci.yml/badge.svg)](https://github.com/remade-with-rust/rusty_alloc/actions)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![remade with rust](https://img.shields.io/badge/remade--with--rust-portfolio-orange.svg)](https://github.com/remade-with-rust)
+
 # rusty_alloc
 
-A pure-Rust remake of [mimalloc](https://github.com/microsoft/mimalloc) — the
-v2.4.5 architecture (32 MiB segments, free-list-sharded pages, lock-free
-cross-thread frees), rebuilt from the design rather than transliterated from
-the C.
+A ground-up, pure-**Rust** general-purpose **allocator** — the mimalloc v2.4.5
+architecture rebuilt from the design rather than transliterated from the C. No
+C in the dependency tree, permissive licence, and a safety property upstream
+does not offer.
+
+## ⚡ The headline
 
-Part of the **[remade-with-rust](https://github.com/remade-with-rust)**
-portfolio, and built to its principles: memory safety first, no C in the
-product, general primitives over one-off fixes, and **measured, not vibed** —
-which is why the performance section below spends as much space on what we
-*haven't* established as on what we have.
+- **Parity with mimalloc on instructions retired**, and ~16% fewer than glibc,
+  on real programs under `LD_PRELOAD`.
+- **A double free aborts instead of corrupting.** Upstream mimalloc accepts it
+  silently in release builds; we detect it on both the local and the
+  cross-thread path and abort, for a measured ~0.4%.
+- **~150 of mimalloc's ~157 `mi_*` entry points**, gated against the C
+  implementation as a differential oracle on every change.
+- **Runs on WebAssembly** with no C toolchain and no emscripten.
 
 > **Status: `0.1.0-alpha.1`.** The allocator is complete and gated. The
-> performance *evidence* is not. Read
-> [What is and isn't measured](#what-is-and-isnt-measured) before depending on
-> this — the short version is that we count instructions, not seconds, and we
-> make no speed claim.
+> performance *evidence* is not. See
+> [What is and isn't measured](#what-is-and-isnt-measured) — we count
+> instructions, not seconds, and make no speed claim.
 
-## What it is
+## Performance (this machine, deterministic)
 
-- **~150 of mimalloc's ~157 `mi_*` entry points**, semantics-for-semantics,
-  gated against the C implementation as a differential oracle.
-- **A double free is detected and aborted, not silently accepted.** Upstream
-  mimalloc does not detect this in release builds. We do, at a measured cost of
-  ~0.4% on perl and ~0.2% on sqlite. Silently handing the same block to two
-  owners is the exact failure this project exists to prevent, so the check is
-  the point rather than an overhead.
-- **No C anywhere in the product.** The C mimalloc in this repo is a
-  development-only oracle: never a dependency, never published.
-- **Runs on WebAssembly** (`wasm32-unknown-unknown`) with no C toolchain and no
-  emscripten — `memory.grow`, single linear memory, gated by a self-test that
-  executes inside a real VM.
+Instructions retired under callgrind, x86-64 Linux, real programs via
+`LD_PRELOAD`. Repeats to 4–6 significant figures.
 
-## What is and isn't measured
+| workload | vs mimalloc | vs glibc |
+|---|---:|---:|
+| lua | **0.99** | 0.84 |
+| perl | **1.01** | 0.83 |
+| sqlite | **1.00** | 1.00 |
 
-### Measured — instructions retired
+**Method.** `bench/icount-arms.sh`. Instruction counts, not wall-clock — chosen
+deliberately, because this machine's timing noise floor is wider than the
+effect (see below). Counts are immune to scheduler, thermal and load artifacts;
+they are also *not* a measure of time.
 
-Deterministic (callgrind), x86-64 Linux, `LD_PRELOAD` against the real programs:
+### What is and isn't measured
 
-| workload | vs mimalloc | vs glibc |
-|---|---:|---:|
-| lua | 0.99 | 0.84 |
-| perl | 1.01 | 0.83 |
-| sqlite | 1.00 | 1.00 |
+**Wall-clock: measured, and it cannot resolve the difference.**
+`bench/wallclock.sh` runs pinned, ABBA-interleaved, N=31, microsecond timer,
+with a **null arm** — the same allocator compared against itself:
+
+| arm | median ratio |
+|---|---:|
+| **null (rusty_alloc vs ITSELF)** | **1.0117** |
+| perl, rusty_alloc vs mimalloc | 1.0009 |
+| sqlite, rusty_alloc vs mimalloc | 1.0091 |
 
-Parity with mimalloc; roughly 16% fewer instructions than glibc. These repeat to
-4–6 significant figures, so they are claims we can defend.
+The null arm is **1.17%** — wider than either effect. The honest reading is
+**"at parity, below measurement resolution"**. Reproduce on a quiet box with
+`N=31 bash bench/wallclock.sh`.
 
-### NOT measured — and therefore not claimed
+**Not measured, and therefore not claimed:**
 
-- **Wall-clock time.** See [Timing](#timing) below. We have run it; this machine
-  cannot resolve a difference this small, and we are not going to launder that
-  into a speed claim.
-- **The full mimalloc-bench corpus.** Three workloads, not the suite. The
+- The full mimalloc-bench corpus. Three workloads, not the suite — the
   project's own v1 gate (geomean within 10%, no bench >25% behind, RSS within
   15%) is **not yet demonstrated**.
-- **RSS.** No systematic footprint sweep.
-- **aarch64.** The code paths exist and compile. They have never been executed.
+- RSS. No systematic footprint sweep.
+- aarch64. Code paths exist and compile; they have never been executed.
 
 There is no "faster than mimalloc" claim anywhere in this repository, because
 the evidence for one does not exist yet.
 
-### Timing
+## What is this?
 
-`bench/wallclock.sh` runs pinned, ABBA-interleaved, microsecond-resolution
-comparisons at N=31 with a **null arm** — the same allocator against itself.
-The null arm is the floor: any delta smaller than it is noise, not a result.
+A reimplementation, not a binding. There are excellent mimalloc *bindings* for
+Rust; this is not one of them. Every line of the allocator is Rust, the C
+mimalloc in this repository is a development-only differential oracle, and it
+is never a dependency and never published.
 
-Measured on the development machine (N=31, pinned, microsecond timer):
+`unsafe` is confined to the places an allocator genuinely needs it — the OS
+primitive layer, page and segment metadata, and the lock-free cross-thread
+protocol — with a stated invariant on every block, `unsafe_op_in_unsafe_fn`
+denied and `undocumented_unsafe_blocks` denied workspace-wide.
 
-| arm | median ratio |
-|---|---:|
-| **null (rusty_alloc vs itself)** | **1.0117** |
-| perl, rusty_alloc vs mimalloc | 1.0009 |
-| sqlite, rusty_alloc vs mimalloc | 1.0091 |
+## The Remade With Rust ecosystem
 
-The null arm is **1.17%** — wider than either measured effect. The same
-allocator compared against itself differs by more than the difference we are
-trying to detect, so the only honest reading is **"at parity, below measurement
-resolution"**. That is not a hedge; it is what the instrument supports.
-Reproduce it on a quiet box:
+| project | what |
+|---|---|
+| [rusty_alloc](https://github.com/remade-with-rust/rusty_alloc) | this — pure-Rust general-purpose allocator |
+| [rusty_h264](https://github.com/remade-with-rust/rusty_h264) | pure-Rust H.264 encoder and decoder |
+| [Mata Network](https://www.mata.network/) | the parent organisation |
 
-```sh
-N=31 bash bench/wallclock.sh
+## Features
+
+**Allocator core** — 32 MiB segments sliced into 64 KiB spans, free-list-sharded
+pages, the loom-verified four-state cross-thread free protocol, thread
+abandonment and adoption, first-class heaps, arenas, huge allocations, aligned
+allocation with interior-pointer recovery, and the full realloc family.
+
+**Safety** — double-free detection on both the owner and cross-thread paths;
+Miri-clean; a 640-thread churn probe; `debug_checks` for full invariant
+validation; `secure` for guard pages, encrypted free lists and guarded-object
+sampling.
+
+**Portability** — x86-64 and aarch64, Linux and Windows, plus
+`wasm32-unknown-unknown` via `memory.grow`.
+
+## Install
+
+```toml
+[dependencies]
+rusty_alloc-api = "0.1.0-alpha.1"
 ```
 
-## Layout
+| crate | docs | what |
+|---|---|---|
+| [`rusty_alloc`](https://crates.io/crates/rusty_alloc) | [docs.rs](https://docs.rs/rusty_alloc) | allocator core |
+| [`rusty_alloc-api`](https://crates.io/crates/rusty_alloc-api) | [docs.rs](https://docs.rs/rusty_alloc-api) | safe Rust surface — start here |
 
-| path | what |
-|---|---|
-| `crates/rusty_alloc` | allocator core — **published** |
-| `crates/rusty_alloc_api` | safe Rust surface (`GlobalAlloc`, `Heap`, `Allocator`) — **published** |
-| `crates/rusty_alloc_ffi` | `mi_*`-compatible C ABI (cdylib + staticlib) |
-| `crates/rusty_alloc_override` | `malloc`/`free` interposition cdylib (LD_PRELOAD arm) |
-| `crates/rusty_alloc_bench` | Tier-B harness + trace record/replay |
-| `crates/rusty_alloc_wasm` | wasm self-test fixture |
-| `oracle/mimalloc` | C mimalloc @ v2.4.5 — **dev-only oracle**, never a runtime dep |
-| `corpus/mimalloc-bench` | the 1:1 benchmark corpus (submodule) |
-| `docs/LEDGER.md` | one entry per milestone: numbers, method, and every revert |
-| `docs/plans/rusty_alloc_v1.md` | plan of record — API inventory, gate ladder, roadmap |
-
-Only the two crates marked **published** go to crates.io. Everything else is
-`publish = false`: harnesses, fixtures and native artifacts, not libraries.
+The FFI, LD_PRELOAD override, bench and wasm crates are `publish = false`:
+harnesses, fixtures and native artifacts, not libraries.
 
-## Gates
+## Quick start
+
+```rust
+use rusty_alloc_api::RustyAlloc;
 
-Every change runs: Windows + Linux test suites (all features), `clippy -D
-warnings`, Miri, a 640-thread churn probe, a wasm VM self-test, and a
-deterministic instruction-count A/B against the C oracle. `docs/LEDGER.md`
-records what each milestone measured — **including the changes that were
-reverted for being flat or slower**, which is most of them.
+#[global_allocator]
+static ALLOC: RustyAlloc = RustyAlloc;
 
-## Building the oracle (contributors)
+fn main() {
+    let v: Vec<u64> = (0..1_000).collect();
+    println!("{}", v.iter().sum::<u64>());
+}
+```
+
+## Architecture
+
+```
+crates/rusty_alloc            allocator core       (published)
+crates/rusty_alloc_api        safe Rust surface    (published)
+crates/rusty_alloc_ffi        mi_*-compatible C ABI
+crates/rusty_alloc_override   malloc/free interposition cdylib
+crates/rusty_alloc_bench      Tier-B harness + trace record/replay
+crates/rusty_alloc_wasm       wasm self-test fixture
+oracle/mimalloc               C mimalloc @ v2.4.5 — dev-only oracle
+corpus/mimalloc-bench         the 1:1 benchmark corpus
+docs/LEDGER.md                one entry per milestone: numbers, method, reverts
+docs/plans/rusty_alloc_v1.md  plan of record — API inventory, gate ladder
+```
+
+## Benchmarking
 
 ```sh
 git submodule update --init oracle/mimalloc corpus/mimalloc-bench
-bash oracle/build.sh          # builds mi / dmi / smi arms
+bash oracle/build.sh                 # build the C oracle arms
+bash bench/icount-arms.sh            # deterministic instruction A/B
+N=31 bash bench/wallclock.sh         # wall-clock, with a null arm
+bash bench/opscan.sh                 # per-operation scan vs mimalloc
 ```
 
+## Gates
+
+Every change runs Windows + Linux suites (all features), `clippy -D warnings`,
+Miri, a 640-thread churn probe, a wasm VM self-test, and a deterministic
+instruction A/B against the C oracle. [`docs/LEDGER.md`](docs/LEDGER.md)
+records what each milestone measured — **including the changes reverted for
+being flat or slower**, which is most of them.
+
+## Platform support
+
+| target | status |
+|---|---|
+| x86-64 Linux | tested; the LD_PRELOAD and measurement path |
+| x86-64 Windows | tested |
+| aarch64 | compiles; **never executed** |
+| wasm32-unknown-unknown | tested in a VM self-test |
+
 ## License
 
-MIT — see [LICENSE](LICENSE). Vendored dev-only dependencies keep their own
-licenses; none of them ship.
+MIT — see [LICENSE](LICENSE). No GPL or LGPL anywhere in the tree. The vendored
+oracle and benchmark corpus are development-only, keep their own licences, and
+never ship.
+
+## About Mata Network
+
+rusty_alloc is part of the [remade-with-rust](https://github.com/remade-with-rust)
+portfolio from [Mata Network](https://www.mata.network/): foundational software
+rebuilt in Rust, memory-safe by construction, measured rather than asserted.

bench/rebuild-measure.sh

@@ -6,7 +6,7 @@ set -uo pipefail
 cd "$(cd "$(dirname "$0")/.." && pwd)" || exit 1
 export CARGO_TARGET_DIR="$HOME/ra_target"
 echo "== build"
-if ! cargo build --release -p rusty_alloc_override 2>&1 | tail -6; then
+if ! cargo build --release -p rusty_alloc-override 2>&1 | tail -6; then
   echo "BUILD FAILED"
   exit 1
 fi

bench/tls-ceiling.sh

@@ -20,7 +20,7 @@ cd "$root"
 
 echo "building initial-exec variant..."
 RUSTFLAGS='-Z tls-model=initial-exec' CARGO_TARGET_DIR="$HOME/ra_ie" \
-  cargo +nightly build --release -p rusty_alloc_override 2>&1 | grep -E '^error' | head -5
+  cargo +nightly build --release -p rusty_alloc-override 2>&1 | grep -E '^error' | head -5
 
 IE="$HOME/ra_ie/release/librusty_alloc_override.so"
 GD="$HOME/ra_target/release/librusty_alloc_override.so"

corpus/wasm-gate.ps1

@@ -2,7 +2,7 @@
 #
 # `cargo test` cannot execute wasm32-unknown-unknown, so correctness is proven
 # by instantiating the cdylib under Node and calling its self-test export. The
-# same self-test also runs natively via `cargo test -p rusty_alloc_wasm`, so a
+# same self-test also runs natively via `cargo test -p rusty_alloc-wasm`, so a
 # failure here is specifically a WASM failure.
 #
 # Exits non-zero on any failure, so it can be chained into the gate battery.
@@ -14,9 +14,11 @@ cargo check -p rusty_alloc --target wasm32-unknown-unknown
 if ($LASTEXITCODE -ne 0) { Write-Host "WASM GATE FAILED: core crate does not compile"; exit 1 }
 
 Write-Host "== build selftest cdylib"
-cargo build -p rusty_alloc_wasm --target wasm32-unknown-unknown --release
+cargo build -p rusty_alloc-wasm --target wasm32-unknown-unknown --release
 if ($LASTEXITCODE -ne 0) { Write-Host "WASM GATE FAILED: selftest build"; exit 1 }
 
+# NOTE: the PACKAGE is `rusty_alloc-wasm`, but cargo maps the hyphen to an
+# underscore for the artifact, so the file is `rusty_alloc_wasm.wasm`.
 $wasm = "target\wasm32-unknown-unknown\release\rusty_alloc_wasm.wasm"
 if (-not (Test-Path $wasm)) { Write-Host "WASM GATE FAILED: $wasm not produced"; exit 1 }
 

crates/rusty_alloc/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "rusty_alloc"
-description = "Pure-Rust remake of mimalloc v2.4.5 — allocator core"
+description = "Allocator core of the rusty_alloc pure-Rust remake of mimalloc v2.4.5: segments, free-list-sharded pages, lock-free cross-thread frees, first-class heaps, arenas and a mi_*-compatible surface. Detects double frees. MIT."
+documentation = "https://docs.rs/rusty_alloc"
 version.workspace = true
 edition.workspace = true
 license.workspace = true

crates/rusty_alloc_api/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
-name = "rusty_alloc_api"
-description = "Safe Rust-native surface over rusty_alloc: GlobalAlloc, Heap, Allocator"
+name = "rusty_alloc-api"
+description = "Safe Rust surface for the rusty_alloc pure-Rust mimalloc remake: GlobalAlloc, first-class Heap, and the Allocator trait. No unsafe required of callers. MIT."
+documentation = "https://docs.rs/rusty_alloc-api"
 version.workspace = true
 edition.workspace = true
 license.workspace = true

crates/rusty_alloc_bench/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "rusty_alloc_bench"
+name = "rusty_alloc-bench"
 description = "Tier-B native harness + allocation-trace record/replay + G1/G2 gates"
 version.workspace = true
 edition.workspace = true
@@ -17,7 +17,7 @@ path = "src/main.rs"
 rusty_alloc = { path = "../rusty_alloc" }
 
 [dev-dependencies]
-rusty_alloc_api = { path = "../rusty_alloc_api" }
+rusty_alloc-api = { path = "../rusty_alloc_api" }
 libloading = "0.8"
 
 [lints]

crates/rusty_alloc_ffi/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "rusty_alloc_ffi"
+name = "rusty_alloc-ffi"
 description = "mi_*-compatible C ABI over rusty_alloc (cdylib + staticlib)"
 version.workspace = true
 edition.workspace = true

crates/rusty_alloc_override/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "rusty_alloc_override"
+name = "rusty_alloc-override"
 description = "malloc/free interposition cdylib (LD_PRELOAD arm for the 1:1 corpus)"
 version.workspace = true
 edition.workspace = true
@@ -15,7 +15,7 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 rusty_alloc = { path = "../rusty_alloc" }
-rusty_alloc_ffi = { path = "../rusty_alloc_ffi" }
+rusty_alloc-ffi = { path = "../rusty_alloc_ffi" }
 
 [lints]
 workspace = true