# TODO List
Short- and mid-term improvement tasks — actionable, bounded, with status.
This file tracks only work that is **not** blocked on a format change or a
missing concrete consumer. Long-term vision and raw ideas (async I/O,
envelope v2, second `SegmentStore` impl, streaming cipher, parallel flush
workers) live in [ROADMAP.md](ROADMAP.md); shipped work lives in
[CHANGELOG.md](CHANGELOG.md).
Status legend: `[ ]` pending · `[~]` in progress · `[x]` done (recent entries
stay until the next CHANGELOG cut, then move out).
---
## Documentation polish (README + rustdoc)
- `[ ]` **Visually verify README rendering** on GitHub, docs.rs, and a narrow viewport (mobile-width). The ToC, Status block, Cargo features table, and the new `iter_from` / `open_with_report` code blocks all need a human eye — lychee catches link and anchor drift, not rendering regressions. _Standing item since 15-52 §b.3; Cargo features table and the two new code sections added this session widen the surface that needs verification._ Effort: ~15min. _(User action — requires a browser, not a code change.)_
---
## Design decisions deferred
- `[ ]` **Health-check primitive — needs a design decision before any code.** A `fn health(&self) -> Result<HealthReport>` that probes directory writability, lock validity, and disk space. **The design question that must be answered first:** _what does a caller learn from `health()` that they cannot learn from `stats()` + a trial `append()`?_ Three candidate designs, each with a reason it might be Verschlimmbessern:
| Design | What it does | Why it might make things worse |
| --------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `health()` wraps `stats()` | Returns pressure, seq, disk bytes | **Redundant.** `stats()` already returns this. Adding a method that repackages it is API bloat with zero new information. |
| `health()` writes a sentinel file | Write + delete a `.healthcheck` file to probe writability | **Actively harmful on a near-full filesystem.** The write itself can fail (ENOSPC), and writing to a disk you're checking is healthy can worsen the condition. |
| `health()` checks free disk space | Statfs/GetDiskFreeSpace to report free bytes | **Platform dependency.** Needs a new crate (`nix`, `winapi`, or `fs2`) for a feature that `store_pressure()` already approximates. Cross-platform free-space queries have subtle differences (available vs free vs total blocks). |
**Current verdict:** defer until a concrete consumer needs it. The canonical health check today is: call `stats()` for pressure, call `append()` with a trivial item and check for `Err` — the error is already typed (`SegmentError::Io` with `IoSite`). If a consumer needs lock-validity checking, the `Drop` impl already panics if the lock file was tampered with; an explicit probe adds little. **Un-defer when:** a real deployment reports that `stats() + trial append` is insufficient to detect a degraded state (e.g., lock file deleted by an external process while the buffer is open).
---
## See also
- [ROADMAP.md](ROADMAP.md) — long-term direction: async I/O, envelope v2
(streaming CBOR early-stop, Blake3 checksum, compression negotiation,
metadata block, streaming cipher), second `SegmentStore` impl.
- [CHANGELOG.md](CHANGELOG.md) — shipped work.
- [`docs/planning/2026-07-20_05-50_envelope-v2-design-and-v0.6-deferrals.md`](docs/planning/2026-07-20_05-50_envelope-v2-design-and-v0.6-deferrals.md)
— full rationale for the envelope v2 deferrals.
- [`docs/planning/2026-07-21_08-26_flush-worker-and-tier-0-levers.md`](docs/planning/2026-07-21_08-26_flush-worker-and-tier-0-levers.md)
— Pareto plan and addendum covering the perf batch that shipped
(tuning guide, Vec recycling, background-flush pattern example).