# Task Log
> **Navigation**: [Process](./README.md) | [Documentation Root](../README.md)
Current sprint source of truth.
---
## Current Phase
**V0.1: First public release.**
- `keleusma-arena 0.2.0` published to crates.io on 2026-05-10.
- `keleusma-macros 0.1.0` published to crates.io on 2026-05-10.
- `keleusma 0.1.0` ready to publish (dry-run clean against the just-published dependencies).
## Active Milestone
V0.1-M3 substantially complete. The runtime carries Hindley-Milner inference, generics with traits and bounds, compile-time monomorphization, closures (rejected by the safe verifier under the conservative-verification stance), f-string interpolation, target descriptors, hot code swap, the WCET pipelined-cycle and WCMU byte cost model, and the embedding ABI for native functions. Tooling, examples, onboarding documentation, and pre-publication polish passes are complete.
## Outstanding TODO
The single remaining publication-side action is operator-driven.
- **Publish `keleusma 0.1.0` to crates.io.** The two dependencies (`keleusma-arena 0.2.0` and `keleusma-macros 0.1.0`) are live on the registry. `cargo publish -p keleusma --dry-run` succeeds against the registry-resolved dependencies; the package is 91 files, 1.3 MiB unpacked, 330.5 KiB compressed. The agent does not perform `cargo publish`; the operator runs `cargo publish -p keleusma` to complete the V0.1.0 release.
No development-side TODOs remain in this log. Future-work items belong in [BACKLOG.md](../decisions/BACKLOG.md) or [PRIORITY.md](../decisions/PRIORITY.md), where they are tracked alongside their architectural rationale.
## Task Breakdown
### Recent: pre-publication and publication push (2026-05-10)
| ID | Description | Status | Verification |
|----|-------------|--------|--------------|
| V0.1-M3-T54 | BYTECODE_VERSION reset to 1, shebang execution, version triage | Complete | Three asks. (1) `BYTECODE_VERSION` reset from 8 to 1 for the initial public release; pre-publication versions accumulated as the wire format iterated and would never proliferate. The reset is a one-line constant change plus golden-bytes test update (only byte 4 and the CRC trailer change). Triage confirmed `BYTECODE_VERSION` is the only candidate; no other manual version fields exist. (2) Shebang execution. Source scripts: lexer skips line 1 if it begins with `#!`, advancing to line 2 so error messages remain meaningful; `Lexer::new` does the strip. CLI accepts any readable file path (the `.kel` extension shorthand is generalised to "any path that names an existing file"). Compiled bytecode: new `strip_shebang_prefix` helper in `src/bytecode.rs` runs at the entry of `Module::from_bytes` and `Module::access_bytes`, returning the slice past the first `\n` if `bytes.starts_with("#!")`. The CRC trailer covers only the post-strip range so the shebang envelope is not part of the signed payload. CLI auto-detects bytecode versus source through `looks_like_bytecode` which checks for `KELE` magic at offset 0 or after a `#!...\n` envelope; bytecode is loaded through `Vm::load_bytes`, source through the compile pipeline. End-to-end verified: `chmod +x script.kel`, kernel runs through `#!/usr/bin/env keleusma`, returns 42; same for a shebang-prefixed compiled `.bin`. (3) Multiheaded functions with guards confirmed already supported (parser parses `when` clause, AST has `guard: Option<Box<Expr>>`, compiler dispatches accordingly, test exists at `src/parser.rs:1908`). 520 tests pass workspace-wide; clippy, format, rustdoc clean. |
| V0.1-M3-T53 | Bytecode header gains declared WCET and WCMU fields | Complete | The framing header gains two `u32` little-endian fields at offsets 16 and 20 carrying the declared WCET in pipelined cycles and declared WCMU in bytes per Stream-to-Reset slice. Convention: `0` means auto (runtime computes via the verifier as it always has); `u32::MAX` means overflow (the producer attempted to compute a bound but the result exceeded the field's range; safe `Vm::new` rejects with new `LoadError::WcetOverflow` or `LoadError::WcmuOverflow`); other values are the producer's declared bound mirrored from the rkyv body. `BYTECODE_VERSION` 7 → 8. `HEADER_LEN` 16 → 24, divisible by 8 to preserve rkyv body alignment. The compiler runs `verify::wcet_stream_iteration` and `verify::wcmu_stream_iteration` over Stream chunks at end of `compile_with_target` and populates `Module::wcet_cycles` and `Module::wcmu_bytes` with the maximum across them; atomic-total programs (no Stream chunks) ship with `0`. Golden bytes test updated to pin the new 160-byte serialization of `fn main() -> i64 { 1 }`. `examples/zero_copy_demo.kel.bin` regenerated (252 → 268 bytes); `examples/zero_copy_include_bytes.rs` BYTECODE_LEN constant bumped accordingly. 520 tests pass workspace-wide; clippy, format, rustdoc clean. `cargo publish -p keleusma --dry-run` clean against the registry-resolved deps. |
| V0.1-M3-T52 | Documentation polish for keleusma-macros | Complete | README gained "Supported Input Shapes" enumerating accepted (named-field structs, unit/tuple/struct-style-variant enums) and rejected inputs (tuple structs, unit structs, unions). Module-level and derive-fn doc comments expanded with the same enumeration plus a docs.rs link to the parent trait. Crate stays intentionally minimal. Dry-run packages 8 files at 20.3 KiB compressed. 520 tests pass; clippy, format, rustdoc clean. |
| V0.1-M3-T51 | Publication-readiness verification for keleusma-arena and keleusma-macros | Complete | Both crates verified ready. Arena 0.2.0 dry-run packages 13 files at 77.1 KiB; tests pass under stable, MSRV pin (Rust 1.85) with both default and no-default-features, and against `thumbv7em-none-eabihf`. Macros gained per-crate LICENSE (copy of workspace LICENSE) and CHANGELOG.md (Keep a Changelog format with implementation-detail framing). Both dry-runs clean. 520 tests pass. |
| V0.1-M3-T50 | Move KString out of keleusma-arena | Complete | The `KString` type alias and its `&str`-specific allocation logic moved from `keleusma-arena` to a new `keleusma::kstring` module. Arena retains the generic `ArenaHandle<T>` mechanism and gains a public `unsafe fn from_raw_parts(ptr, epoch) -> Self` constructor for downstream typed wrappers. KString is now a newtype over `ArenaHandle<str>` (the orphan rule forbids inherent impls on foreign type aliases). Three KString-specific arena tests replaced with three `arena_handle_*` tests using `from_raw_parts` against a u64. Arena's `epoch_handle` example rewritten to demonstrate `ArenaHandle<u64>`. Arena CHANGELOG and README updated; keleusma main CHANGELOG gained KString entry. 520 tests pass. |
| V0.1-M3-T49 | keleusma-arena 0.2.0 publication readiness | Complete | Version bumped from 0.1.0 (already on crates.io) to 0.2.0. SemVer-correct minor bump under 0.x, signaling the substantive new public surface (epoch counter, `ArenaHandle<T>`, `EpochSaturated`, `Stale`, safe `Arena::reset` returning `Result`, `force_reset_epoch`, `reset_unchecked`, `reset_top_unchecked`, `epoch`, `epoch_remaining`). The 0.1.0 surface preserved unchanged; addition is purely additive. CHANGELOG and README updated. New `epoch_handle` example. Sibling crate dep version requirements bumped to `"0.2"` across keleusma, keleusma-cli, and keleusma-bench. |
| V0.1-M3-T48 | Pre-publication polish pass | Complete | Five items closed. (1) Four rustdoc warnings fixed (private-item links rewritten as prose; `Vm::reset_arena` corrected to `Vm::reset_after_error`). (2) `Module` re-exported from crate root so embedders write `keleusma::Module`. (3) New `CHANGELOG.md` at workspace root in Keep a Changelog format documenting V0.1.0 across language, runtime, verification, host interface, tooling, examples, documentation. (4) CI workflow split MSRV per-crate (arena 1.85, keleusma 1.87) and gained a `no-std` job building keleusma against `thumbv7em-none-eabihf`. (5) `keleusma-macros` Cargo.toml metadata enriched and a new README marks it as an implementation-detail crate. 519 tests pass; format, clippy, rustdoc clean. |
### V0.1-M3-T1 through T47 (rolled up)
| Range | Theme | Status |
|-------|-------|--------|
| T1–T9 | Type checker standalone, integration into compile pipeline, gap closing | Complete. New `src/typecheck.rs` with two-pass design. Multiheaded parameter types, native call distinguishing, pattern type checking against scrutinee, match exhaustiveness for enum/bool/unit/other, P3 error-recovery model via `Vm::reset_after_error`. |
| T10–T12 | Host-owned arena migration, KString boundary, native ABI context | Complete. Vm migrated to a borrowed shared reference to a host-pre-allocated `Arena` under a new `'arena` lifetime. Operand stack migrated to arena-allocated `Vec<T, BottomHandle>`. `Value::KStr(KString)` arena-allocated dynamic string boundary. New `NativeCtx<'a>` carrying arena context for natives that allocate arena-backed strings. Float width log2 added to wire format header (BYTECODE_VERSION 5). |
| T13–T25 | Hindley-Milner inference, generics, traits, monomorphization, closures | Complete. Robinson unification with occurs check. `Type::Var` inference variables. Generic functions, structs, enums with type parameters and trait bounds. Compile-time monomorphization with inference reach across literals, identifiers, function and method calls, casts, enum variants, struct constructions, tuple and array literals, if and match arms, field access, tuple-index, and array-index. Closures with environment capture and transitive nested capture; rejected by the safe verifier per the conservative-verification stance because indirect dispatch through `Op::CallIndirect` cannot be statically bounded. |
| T26–T38 | Target portability, decode optimization, B-list closures, conservative-verification stance, release-readiness | Complete. Target descriptor for cross-architecture portability with `host`, `wasm32`, `embedded_32`, `embedded_16`, `embedded_8` presets. Per-op decode caching for archived bytecode. B7 error propagation through resume value pattern with optional `Vm::resume_err` documentation alias. B8 (shared arena across multiple Vm instances) closed as not-applicable. Conservative-verification stance documented in [LANGUAGE_DESIGN.md](../architecture/LANGUAGE_DESIGN.md#conservative-verification); compile-time and verify-time rejection enforced for `Op::CallIndirect` and `Op::MakeRecursiveClosure`. CLAUDE.md, top-level README, and Cargo.toml metadata refreshed. |
| T39–T41 | WCET cycle and WCMU byte cost model | Complete. New `bytecode::CostModel` struct with `value_slot_bytes` and `op_cycles` fields. Bundled `NOMINAL_COST_MODEL` constant. WCET unit terminology shifted to "pipelined cycles" with explicit definition; calibration-factor / dilation-factor industry terminology adopted. New `keleusma-bench` workspace member calibrates pipelined cycles per opcode through a `CycleCounter` trait with built-in implementations for x86_64 (RDTSC), AArch64 (CNTVCT_EL0), and a portable `Instant`-based fallback; emits a generated `CostModel` source fragment. |
| T42 | Standalone CLI | Complete. New `keleusma-cli` workspace member providing the `keleusma` binary with `run`, `compile`, and `repl` subcommands modeled after Rhai's CLI ergonomics. Shorthand `keleusma file.kel` runs a script. Installs through `cargo install --path keleusma-cli --bin keleusma`. |
| T43 | Onboarding documentation | Complete. New `docs/guide/` section with `GETTING_STARTED.md`, `EMBEDDING.md`, `WHY_REJECTED.md`. Eight standalone scripts under `examples/scripts/` covering arithmetic, structs, enums, for-in, pipelines, multiheaded dispatch, f-strings, and method dispatch. Each runs through `keleusma run`. |
| T44–T47 | SDL3 audio piano-roll example | Complete. Three-channel piano-roll: square-wave melody, triangle-wave bass, square-wave harmony, four-bar I-vi-IV-V progression in C major auto-looping at 120 BPM with 16th-note tick resolution. SDL3 audio thread synthesizes samples; Keleusma main thread sequences notes per tick; thread-safe handoff via `Arc<Mutex<[Voice; 3]>>`. Hot code swap between two precompiled songs at the reset boundary; `s` + Enter to swap, Enter alone to quit. Example refactored from a workspace-member to a feature-gated `[[example]]` (`required-features = ["sdl3-example"]`) so workspace builds remain SDL3-free. Documentation pass surfaced the example from the top-level README, the docs knowledge-graph index, the embedding guide (where two latent doc bugs in the hot-swap snippet were also fixed), and the getting-started guide. |
### Earlier milestones (rolled up)
| Milestone | Theme | Resolved Decisions |
|-----------|-------|--------------------|
| V0.0-M0 | Crate extracted from Vows of Love and War workspace; knowledge graph created | R1–R21 |
| V0.0-M1 | Block-structured ISA transition, productivity verification, WCET analysis | R22, R23 |
| V0.0-M2 | For-in over arrays, tuple literals, utility natives, README, formal related work pass | (RELATED_WORK Sections 1–7) |
| V0.0-M3 | Data segment specification and implementation, singular-block enforcement, fixed-size field validation, slot-bounds verification, host slot-based interop, hot swap API on `Vm` | R24–R29 |
| V0.0-M4 | Cargo workspace conversion with `keleusma-macros`; `KeleusmaType` trait and derive; `IntoNativeFn` family; `register_fn` and `register_fn_fallible`; audio and utility natives migrated | R30 |
| V0.0-M5 | Two-string-type runtime discipline (`Value::StaticStr`, `Value::DynStr`); cross-yield prohibition on dynamic strings; documentation of the fifth (memory) guarantee | R31, R32, R33 |
| V0.0-M6 | Dual-end bump-allocated arena via `keleusma-arena` (extracted as a standalone crate, published as `keleusma-arena 0.1.0` on 2026-05-08); WCMU instrumentation per-op; native attestation API; auto-arena sizing through `Vm::new_auto`; bounded-iteration loop analysis; call-graph WCMU integration | R34–R38 |
| V0.1-M1 | Precompiled bytecode wire format with magic, total-length, version, target word and address widths (encoded as base-2 exponents), CRC-32 algebraic self-inclusion trailer; trust-skip API via `unsafe Vm::new_unchecked`; golden-bytes test pinning the exact serialization | R39 |
| V0.1-M2 | Phase 1: body format switched from postcard to rkyv 0.8 (BYTECODE_VERSION 4). Phase 2: zero-copy execution against a borrowed `ArchivedModule` via `Vm::view_bytes_zero_copy` with the `'a` lifetime parameter; per-access converters from archived to owned types for the execution loop | R40 (P10 fully resolved) |
## History
| Date | Summary |
|------|---------|
| 2026-05-10 | `keleusma-arena 0.2.0` and `keleusma-macros 0.1.0` published to crates.io. `keleusma 0.1.0` ready; awaits manual `cargo publish`. Process-file compaction pass before main-crate publication. |
| 2026-05-10 | Pre-publication polish (T48–T52). Rustdoc warnings cleared, `Module` re-exported from crate root, root `CHANGELOG.md` added, CI MSRV split per-crate, no_std build verified against `thumbv7em-none-eabihf`. `KString` moved from `keleusma-arena` to a new `keleusma::kstring` module so the allocator crate retains only the generic `ArenaHandle<T>` mechanism. `keleusma-macros` gained LICENSE, CHANGELOG, and expanded documentation. Arena bumped to 0.2.0 with the additive epoch surface; sibling crates updated to depend on `"0.2"`. |
| 2026-05-10 | Cost-model calibration tool, standalone CLI, onboarding docs, SDL3 audio example with hot code swap (T39–T47). New workspace members `keleusma-bench` and `keleusma-cli`. New `docs/guide/` section. New `examples/piano_roll.rs` feature-gated under `sdl3-example`. |
| 2026-05-09 | V0.1-M3 development sweep (T1–T38). Type checker, host-owned arena, generics, closures, monomorphization, target descriptor, conservative-verification stance and compile-time enforcement. |
| 2026-05-08 | `keleusma-arena 0.1.0` published to crates.io. Pre-publication polish for the standalone allocator: drop-impl audit, miri stacked-borrows and tree-borrows verification, `mixed_allocator` example, CHANGELOG in Keep a Changelog format. |
| 2026-05-08 | V0.1-M1 precompiled bytecode wire format with CRC trailer, length and target widths in header (R39). V0.1-M2 rkyv format and zero-copy execution against borrowed archived bytecode (R40). |
| 2026-05-08 | V0.0-M6 arena allocator, WCMU instrumentation, native attestation, auto-arena sizing, bounded-iteration loop analysis (R34–R38). |
| 2026-05-08 | V0.0-M3 through V0.0-M5: data segment, hot swap API, cargo workspace, marshalling layer, two-string discipline (R24–R33). |
| 2026-05-08 | V0.0-M2 for-in arrays, tuple literals, utility natives, formal related-work pass with citations across knowledge graph. |
| 2026-05-08 | V0.0-M1 productivity verification and WCET analysis (R22–R23). |
| 2026-03-02 | Crate extracted from Vows of Love and War workspace. Knowledge graph created. Block-structured ISA transition (R22). |