Tracking: v0.1.0 release

[chrischtel]

Umbrella tracking issue for the first tagged, announced, public release of K2.

K2 is Windows-only today; the language, comptime/metaprogramming engine, standard library, and core tooling are substantial and covered by a 200+ test suite (currently green, vm corpus 74/74).

What v0.1.0 is

The first public milestone: a tagged GitHub release with prebuilt Windows binaries, accurate docs, an honest "what works / what doesn't" story, and an announcement. Not feature-complete, not multi-platform — a usable, documented, experimental snapshot.

---

✅ Landed (the foundation)

• Language — structs/packed structs, enums + payloads, exhaustive match (ranges/string/guard patterns; value-producing match and if expressions), ints i8–i128/u1–u128 + floats, pointers/arrays/slices/optionals with debug checks, casts, distinct/opaque types, monomorphized generics, UFCS extension methods (incl. on temporaries), in-struct methods, lambdas + iterators.
• Errors & memory — T ! E, fail, ?, catch, !!, ??, success/error defer modes, tail-forwarding, qualified error types; Arena zones with compiler-enforced non-escape.
• Comptime & metaprogramming — a bytecode VM that executes the compiler's own IR; #run/#if; #quote/#insert with re-checking + hygiene; template macros with $-splice; #for; #parse; the ast.* value surface you can match on; #compiler hooks + compiler_decls(); #derive.
• Reflection — type_info, typeid, Any → std.serde (reflection-driven JSON, no per-type code).
• Generics — $T: constraints, where { … } predicates, named constraints, output type params.
• Modules — file-as-module, :: namespacing, per-module name mangling.
• C interop — #extern, Win64 by-value aggregate ABI, thin C fn pointers, k2 bindgen (libclang → K2).
• Backend / build — LLVM backend, in-process LLD + a from-scratch K2 linker (k2lnk), k2 build running build.k2 in the comptime VM → real exes/DLLs.
• Standard library (25 modules) — io, fmt, mem, strings, slice, vec, map, list, heap, math, rand, color, bits, ptr, path, time, crypto, serde, net (TCP/UDP), atomics, thread, fs, process, c, build.
• Tooling — k2 lsp (diagnostics/completion/hover/def/symbols), a tree-sitter grammar + Zed extension, and the #test comptime test lane (a failed assertion fails the build like a type error).

---

🎯 Before v0.1.0

Release mechanics

• Decide the version & clean up tags. Stray local tags v0.1.0–v0.1.4 already exist (unpushed, no releases — dev checkpoints from 2026-06-24). Recommend: delete the unpushed dev tags and tag the real release v0.1.0 (or start at v0.2.0).
• Drop -dev at tag time: CLI version and build.zig.zon 0.1.0-dev → 0.1.0.
• CHANGELOG.md / release notes — none exists yet.
• Cut a GitHub Release with prebuilt Windows binaries (k2.exe + k2lld.dll / runtime DLLs) and an LLVM/SDK note.

Docs & consistency — done in this pass, verify

• README status table & stdlib table rewritten to match reality.
• ROADMAP.md rewritten (landed vs v0.1.0 vs after; real known bugs).
• docs/15 test-runner status; docs/00 doc index completed.
• build.zig.zon version aligned to the CLI (0.1.0-dev).
• Examples sweep — confirm everything under examples/ builds & runs on a clean checkout.
• Getting started verified from scratch (Zig + LLVM; Windows-only caveat up front).

Correctness gaps — fix or document for 0.1.0

• Interface-through-interface dispatch → LLVM verification error (blocks a fully generic std.fmt.Display). Fix, or document as a known limitation.
• Struct/aggregate == → backend can't emit an aggregate compare (fails at runtime, not just comptime). Document as a known limitation; the real fix is the reflection-driven structural compare (post-0.1.0).
• Triage any other accepted-but-incompletely-lowered constructs.

Announcement

• Short post (the metaprogramming-VM angle is the hook) with a runnable example and the honest "Windows-only, experimental" framing.

---

⚠️ Known limitations (ship-with, document)

• Windows x86-64 only — the frontend is platform-independent; the Linux/ELF backend is designed (docs/14) but not implemented.
• No external packages — single-tree until the package manager (docs/16).
• Interface-through-interface dispatch; struct == (above).

---

🗺️ Explicitly post-0.1.0 (not blocking)

• Testing — runtime lane (k2 test, per-test zones + leak checks, TTY/TAP/JSON), reflection-driven structural diffs (also unlocks struct ==), property tests, snapshots (docs/17 §5).
• Tooling — k2 fmt, k2 doc, k2 repl, LSP v2/v3.
• Linux/ELF backend (docs/14); package manager (docs/16).
• Wider metaprogramming — more ast.* node kinds, building ast.* without #quote, bare-call macros, typed macro params, an auto-generated std.ast.
• Interface composition / owned dynamic objects / downcasting, SIMD, contracts (#require/#ensure); #when/#bench/#on_start/#on_exit.

---

Related issues

• Attributes needing new infrastructure: #when, #test, #bench, #on_start/#on_exit #5 — attributes needing infrastructure. #test is now done (comptime lane); #when, #bench, #on_start/#on_exit remain.
• Tracking: comptime VM / std.compiler / ast.* open work #3 — comptime VM / std.compiler / ast.* tracking.

[chrischtel]

Language changes for 0.1.0 — landed

Implemented the contained language items (the rest stay documented limitations):

• Named-field struct literals — .{ .x = 1, .y = 2 } (any order; rejects unknown/missing fields).
• Default field values — name: T = expr; fills omitted named fields and trailing positional/.{} slots.
• Overflow policy decided + documented — plain +/-/* trap in debug, wrap in release (never UB); +%/-%/*% always wrap.
• Operator precedence locked — verified the ladder (incl. bitwise-tighter-than-comparison, fixing C's a & b == c wart) and that chained comparison (1 < 2 < 3) is rejected, not misparsed. Pinned by regression tests.

Each landed as a small commit on main with tests; docs in docs/01 (precedence) and docs/02 (literals, defaults, overflow). Still documented as known limitations: struct ==, static interface constraints, non-capturing lambdas.

[chrischtel]

Correctness gaps — fixed

Both flagged bugs are fixed, plus the siblings triage turned up:

• Interface-through-interface dispatch — turned out to be already fixed; no longer reproduces. Locked with a regression test (a *Wrapper method calling a method on a *Display arg).
• Struct/aggregate == — now lowers field-by-field (recursing into nested structs and string fields). Works at runtime and on the comptime VM, so t.eq on structs folds too.
• Triage of other aggregate == — found and fixed the siblings: arrays (elementwise), non-byte slices ([]T, length + element loop), and payload enums (e == .variant → discriminant check). Comparing two full payload-enum values now gives a clean use match error instead of an LLVM crash.

Suite green (vm corpus 74/74); each landed as a small commit with regression tests. Remaining documented limitations: == on two payload-enum values, static interface conformance constraints, non-capturing lambdas.

[chrischtel]

Remaining-limitations triage

Tested all three rigorously; only one was a genuine missing feature:

• == on two payload-enum values — implemented for scalar payloads (same variant + equal payload; works at runtime and comptime). Non-scalar payloads (struct/string/array) still error cleanly (use match).
• Non-capturing lambdas — turned out to be a mislabel: lambdas do capture (multi-capture and higher-order both verified). The only restriction is returning a capturing closure, which needs an *Arena by design. Docs corrected.
• Static interface constraints — $T: Iface conformance is enforced (a non-conforming type is rejected). The remaining gap is calling the interface's methods directly on the bound/implementing type — interface-impl methods are reachable only through a *Iface value today (g.val() doesn't resolve). That's a deeper change (impl methods aren't sema symbols; needs hoisting + a resolution path + IR rework) — left as a focused follow-up to avoid regressing working interface dispatch. where T: Iface clause syntax also isn't parsed (use $T: Iface).

[chrischtel]

Interface constraints — now implemented

The deferred piece is done: an interface's methods are now callable directly on the implementing type and on a $T: Iface-constrained generic (resolved at instantiation), not just through a *Iface value.

• g.val() on a concrete Good that Good as Show { val } implements → works.
• fn($T: Show, x: *T) { x.val() } → works (conformance still enforced; Bad is still rejected).
• Methods with arguments work; dynamic and interface-through-interface dispatch unchanged.

How: sema records the resolved {type}.{interface}.{method} in a new impl_method_calls map (only when normal resolution fails and the type implements an interface declaring the method — so it can't disturb existing dispatch); IR emits a direct call to the function the vtable lowering already produces. Suite green (vm corpus 74/74), with regression tests.

Only where T: Iface clause syntax remains unparsed (use $T: Iface). With this, all three remaining-limitation items from the earlier triage are resolved (payload-enum ==, lambdas-capture mislabel, interface constraints).

[chrischtel]

where T: Iface clause syntax — added

fn($T, x: *T) -> i32 where T: Show { return x.val(); } now parses and behaves identically to the inline $T: Show form — conformance enforced, methods callable, comma-separated bounds supported (where T: A, U: B). The where { … } predicate-block form is unchanged (disambiguated by a leading {), and $T may now appear without an inline constraint.

That closes the last interface sub-item. All remaining-limitation items from the triage are now resolved. Suite green (vm corpus 74/74), with regression tests.