Add v0.4 re-implementation plan

docs/v0.4-plan.md

@@ -0,0 +1,126 @@
+# Bakelite 0.4 — Remaining Work
+
+Items to implement after the modernization PR chain (PRs #1–7) lands.
+Reference: original PR #10 (`feature/modernization-and-async`).
+
+## 1. Simplified type system (breaking change)
+
+The biggest change in 0.4. All `bytes[N]`, `string[N]`, and `T[N]` become
+variable-length with max capacity N. No more fixed-length semantics.
+
+### Wire format
+
+- `bytes[N]` — 1-byte length prefix + up to N bytes
+- `string[N]` — null-terminated, up to N chars (no padding)
+- `T[N]` — 1-byte length prefix + up to N elements
+
+### Grammar changes
+
+The Lark grammar (`protodef.lark`) needs updating:
+
+- `bytes[N]` and `string[N]` require a size — no more bare `bytes[]`/`string[]`
+- `T[N]` always requires a size
+- The `prim_variable` rule becomes `prim_sized` with higher priority
+
+### Code generator changes
+
+**Python** — Arrays and bytes use length-prefix encode/decode in the generated
+`pack()`/`unpack()` methods. Strings use null-termination helpers.
+
+**cpptiny** — New `SizedArray<T, N>` template with vector-like API (`size()`,
+`push_back()`, iterators). Strings map to `char[N+1]`. The serializer
+(`serializer.h`) gains variable-length read/write helpers.
+
+**ctiny** — `bytes[N]` and `T[N]` use inline anonymous structs:
+`{ T data[N]; uint8_t len; }`. Strings map to `char[N+1]`.
+
+### Other effects
+
+- Remove heap parameter from ctiny/cpptiny decode functions
+- Structs become self-contained with inline storage
+- Parser type representation (`types.py`) needs adjustment — the `size` field
+  on `ProtoType` becomes the max capacity
+- All tests and examples need updating for new wire format
+
+### New module: `sizes.py` + `bakelite info` command
+
+A size calculator (`bakelite/generator/sizes.py`) that computes min/max wire
+sizes for every struct and protocol-level RAM estimates for embedded targets.
+
+Key types:
+- `SizeInfo(min_size, max_size, kind)` — where kind is `FIXED` or `BOUNDED`
+- `StructSizeInfo(name, size)`
+- `ProtocolSizeInfo` — protocol-level aggregation including CRC overhead,
+  COBS framing overhead, and estimated RAM for ctiny/cpptiny
+
+The `bakelite info -i <file>` command renders this as a rich table (via `rich`)
+or JSON (`--json`). Add `rich` as a dependency.
+
+## 2. Documentation rewrites
+
+### Protocol specification (`docs/protocol.md`)
+
+Full rewrite of the protocol spec:
+- Replace HTML tables with Unicode box-drawing diagrams
+- Remove unimplemented "Not for V1" sections
+- Add quick reference table for all types
+- Add formal grammar reference
+- Reorganize into: Overview → Types → Structs → Enums → Protocol blocks
+
+### Python docs (`docs/python.md`)
+
+- Add async examples using `messages()` iterator
+- Document `async_=True` parameter
+- Update version requirement to Python 3.13+
+- Add runtime generation steps to quickstart
+
+### CLAUDE.md
+
+- Add project purpose, target platforms, architecture overview
+- Document project structure including templates, runtimes, examples
+- Add 80% code coverage requirement
+
+## 3. Benchmarking suite
+
+Cross-architecture benchmarking under `bench/`:
+
+### Structure
+
+```
+bench/
+  harness/          — C/C++ benchmark programs (one per protocol × language)
+  protocols/        — .bakelite protocol definitions (simple, framing, serialize, typical)
+  scripts/
+    run_benchmarks.py      — orchestrate builds and measurements
+    download_toolchains.py — auto-download cross-compilers
+    analyze.py             — parse results
+```
+
+### Targets
+
+- ARM Cortex-M0 (thumb), Cortex-M3 (thumb2)
+- AVR ATmega328P
+- RISC-V RV32IMC
+- x86-64
+
+### Metrics
+
+- Code size (text, data, bss)
+- RAM usage
+- Instruction count
+- Stack usage (via `-fstack-usage`)
+- Generates disassembly for manual analysis
+
+### Toolchains
+
+Auto-downloaded to `bench/toolchains/`:
+- xPack ARM GCC
+- xPack RISC-V GCC
+- ZakKemble AVR GCC
+
+## 4. Copyright / housekeeping
+
+Already handled in PR #7. If anything was missed:
+- License year → 2025
+- Email → emma@emmaponders.com
+- Applies to: LICENSE.md, pyproject.toml, template headers, bin/update