# `os_slab_vault` — Complete crate overview (for alisio85)

This is a single, comprehensive document describing the crate: its purpose, scope, API, safety
model, documentation set, CI/release automation, and how to publish it to crates.io and GitHub.

> **License**: MIT  
> **Attribution requirement**: Portions were generated by an AI assistant (ChatGPT) based on an idea by **alisio85**.

## 1) What this crate is (and why it exists)

### 1.1 Mission

`os_slab_vault` is a **dependency-free**, **`no_std`-first** generational slab/object-pool.

It exists to solve a kernel-class problem:

- You want a **fixed-capacity**, allocation-free container for kernel objects.
- You must avoid stale-index bugs when slots are freed and reused.
- You want something tiny, auditable, and deterministic.

### 1.2 What it does NOT do (by design)

- No dynamic growth (no heap, no `alloc`).
- No locking or synchronization.
- No platform-specific code (works on bare metal and hosted environments).

## 2) High-level design

### 2.1 Fixed-capacity array + free-list

`Slab<T, N>` stores:

- `values: [MaybeUninit<T>; N]`
- `occupied: [bool; N]`
- `generation: [u32; N]`
- a singly-linked free list (`free_head`, `free_next`)

Insertion:

- pops one index from the free-list
- writes the value into that slot
- marks it occupied

Removal:

- checks `(index, generation)` match
- reads and returns the value
- marks slot vacant
- bumps generation
- pushes slot back on free-list

### 2.2 Generational handle (`Key`)

`Key` carries:

- `index`: slot index
- `generation`: slot generation counter

Every access checks:

- index in bounds
- slot occupied
- generation matches

If any fails, access returns `None`.

### 2.3 Generation policy (reserved 0)

Generation starts at 1 and is incremented on free.

- If it wraps to 0, it is normalized back to 1.
- This makes an all-zero `Key` (common in zeroed kernel memory) unlikely to be valid.

## 3) Public API (what users call)

The crate intentionally exposes only 3 public items:

- `Slab<T, N>`
- `Key`
- `InsertError`

### 3.1 `Slab<T, N>` core methods

- `new() -> Slab<T, N>`
- `capacity() -> usize`
- `len() -> usize`
- `is_empty() -> bool`
- `is_full() -> bool`
- `insert(value: T) -> Result<Key, InsertError>`
- `get(key: Key) -> Option<&T>`
- `get_mut(key: Key) -> Option<&mut T>`
- `contains_key(key: Key) -> bool`
- `remove(key: Key) -> Option<T>`
- `clear()`
- `iter() -> Iter` (yields `(Key, &T)`)
- `iter_mut() -> IterMut` (yields `(Key, &mut T)`)

### 3.2 `Key` utilities

- `from_parts(index: u32, generation: u32) -> Key`
- `index() -> u32`
- `generation() -> u32`
- `into_parts() -> (u32, u32)`

`Key` implements `Copy`, `Eq`, `Hash`, and `Debug`.

## 4) Safety model (what makes it sound)

### 4.1 Where `unsafe` exists

Internally the crate uses `MaybeUninit<T>` to avoid requiring `T: Default` and to keep everything
allocation-free. That requires `unsafe` for:

- writing into an uninitialized slot (`write`)
- referencing initialized values (`assume_init_ref`, `assume_init_mut`)
- reading/dropping initialized values (`assume_init_read`, `assume_init_drop`)

### 4.2 The invariants enforced by the implementation

For each slot `i`:

- If `occupied[i]` is true, then `values[i]` is initialized.
- If `occupied[i]` is false, `values[i]` is treated as uninitialized and never read/dropped.
- Every inserted value is dropped exactly once (remove/clear/drop).

All `unsafe` blocks are documented in rustdoc in the code.

## 5) Documentation set (what files exist and why)

This repo contains:

- `README.md`: short pitch + quick example + pointers
- `docs/MANUAL.md`: ultra-detailed user manual
- `docs/COOKBOOK.md`: practical recipes
- `docs/SAFETY.md`: safety/auditing guide
- `docs/DESIGN.md`: rationale and trade-offs
- `docs/FAQ.md`: common questions
- `docs/HANDLES_AND_GENERATIONS.md`: deeper conceptual explanation
- `docs/SEMVER.md`: versioning policy
- `docs/CI_AND_RELEASE.md`: how CI/publish works

## 6) CI + crates.io auto-publish (GitHub Actions)

### 6.1 CI (`.github/workflows/ci.yml`)

Runs on pushes and PRs:

- `cargo fmt -- --check`
- `cargo build --no-default-features` (validates `no_std`)
- `cargo build --features std`
- `cargo test --features std`
- `cargo clippy --all-targets --all-features -- -D warnings`
- `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features`

### 6.2 Publish (`.github/workflows/publish.yml`)

Triggers on:

- tag push matching `v*` (example: `v0.1.0`)
- or manual `workflow_dispatch`

It reruns the same quality gates, then executes:

- `cargo publish`

It expects a GitHub repo secret:

- `CARGO_REGISTRY_TOKEN` (crates.io API token)

## 7) crates.io and docs.rs readiness

The crate is configured for docs.rs in `Cargo.toml` via:

- `package.metadata.docs.rs.all-features = true`
- `rustdoc-args = ["-D", "warnings", "--cfg", "docsrs"]`
- additional targets list including `x86_64-unknown-none`

All code is documented with rustdoc, and docs are expected to build warning-free.

## 8) How to publish to crates.io (local steps)

1. Ensure you can build/test locally:
   - `cargo fmt -- --check`
   - `cargo test --features std`
   - `cargo clippy --all-targets --all-features -- -D warnings`
   - `set RUSTDOCFLAGS=-D warnings; cargo doc --no-deps --all-features`

2. Dry run publish:
   - `cargo publish --dry-run`

3. Real publish (manual option):
   - `cargo publish`

Or use the GitHub Action by pushing a tag `vX.Y.Z` after setting the secret.

## 9) GitHub publication under `github.com/alisio85`

### 9.1 What I can do automatically in your environment

In this environment **`gh` (GitHub CLI) is not installed**, so I cannot create the repository
through GitHub’s API directly. I *can* still:

- initialize a git repository in `os_slab_vault/`
- create commits
- set a remote URL
- attempt to push (this will succeed only if your machine has credentials configured for GitHub)

### 9.2 Recommended push method (works with HTTPS)

If you have Git installed and a GitHub token cached, the push will work with:

- remote: `https://github.com/alisio85/os_slab_vault.git`

### 9.3 Release flow on GitHub

After the repo exists on GitHub and `CARGO_REGISTRY_TOKEN` secret is set:

- create tag `v0.1.0`
- push the tag
- Actions publishes to crates.io automatically

## 10) What makes this crate “independent”

- `Cargo.toml` has **no dependencies**
- core implementation uses only `core`
- optional `std` feature is only for tests/debug formatting

## 11) Quick sanity checklist for you

- ✅ `cargo build --no-default-features`
- ✅ `cargo build --features std`
- ✅ `cargo test --features std`
- ✅ `cargo clippy ... -D warnings`
- ✅ `RUSTDOCFLAGS="-D warnings" cargo doc ...`
- ✅ docs folder populated and detailed
- ✅ MIT license includes AI+idea attribution


