Initial release punchlist

This is the release-control checklist for kit's first public release. It turns the current scope decisions into concrete work items. Design details remain in the subsystem docs and roadmaps linked from doc/DESIGN.md and doc/plan/README.md; this file is the cross-cutting release list.

Release scope

Ship

• C11 toolchain: preprocessor, parser/checker, codegen, cc, cpp, as, ld, archive/object tools, byte tools, hash/compress, cas/pkg, and install.
• Curated real-world C library/application build gates, including hosted links against system libraries and platform frameworks.
• Optimization: -O0 and -O1 only. -O2 is not a release feature.
• LTO / whole-program optimization, enabled explicitly and able to run at -O1.
• Content-addressed build coordinator (kit build / <kit/build.h>), layered on CAS and package/trust infrastructure.
• Runtime: target libkit_rt.a, freestanding headers/libc subset, compiler-rt helpers, atomics, setjmp, and coroutines for the release support set.
• JIT runtime (kit run) and IR interpreter (kit run --no-jit) for supported host-compatible targets.
• WebAssembly: single-TU wasm32 output, Wasm/WAT input, and runtime execution with partial WASI Preview1 compatibility.
• Interactive debugger on x64, arm64, and rv64 for Linux, macOS, and FreeBSD.
• Cross-compilation support set:
  • arm64: macOS, Linux, Windows, FreeBSD, freestanding
  • x64: Linux, Windows, FreeBSD, freestanding
  • rv64: Linux, FreeBSD, freestanding
  • rv32: freestanding

Do not ship

• -O2 as a distinct optimization level.
• The Toy frontend as a user-facing language.
• The user-mode ELF emulator.
• File-based/AOT incremental linking.
• Creating dynamic/shared libraries. Release builds may still create executables that link against dynamic libraries.
• Multi-TU Wasm output, Wasm static linking, wasm64, or complete WASI.
• Interactive debugger support on Windows or rv32.

Global release cleanup

• Freeze the public release surface in README/help/docs so it matches the scope above.
• Disable or hide the emulator (KIT_EMU_ENABLED, KIT_TOOL_EMU_ENABLED, docs, help, default tests).
• Hide Toy from user-facing docs and install/help output; keep it as internal test coverage where useful.
• Remove -O2 release claims and make -O2 behavior explicit: either reject it for v1 or document it as an alias for -O1 only if that is intentional.
• Remove or reject dynamic-library creation entry points for release: cc -shared, ld -shared, build-lib -dynamic, and any equivalent flag spellings. Preserve executable links against DSOs.
• Remove incremental-linking claims from docs and make any public reserved entry points either unavailable or clearly unsupported.
• Update src/core/config_assert.c so every release gate is asserted, including RV32 and newer KIT_TOOL_* flags.
• Build and test at least one "release gates" configuration with disabled emulator, no user-facing Toy, and no dynamic-library creation path.

Target support matrix

For each target in the release set:

• kit cc -c produces a valid object with correct predefined macros and data model.
• kit as / inline asm support is either validated or explicitly diagnosed when unsupported.
• kit ld links static executables and relocatable objects where applicable.
• Runtime archive auto-selection works for cc and ld.
• Runtime helpers, atomics, setjmp, and coroutines pass targeted tests.
• Debug info emission and object inspection round-trip.
• Hosted targets validate sysroot/libc integration; freestanding targets validate startup/runtime policy.

Target-specific work:

• Add/validate FreeBSD target parsing and serialization for arm64/x64/rv64.
• Add/validate FreeBSD hosted profiles against a real FreeBSD rootfs for arm64/x64/rv64.
• Add/validate runtime variants for arm64 FreeBSD, x64 FreeBSD, rv64 FreeBSD, arm64 freestanding, and x64 freestanding.
• Validate Windows arm64/x64 object/link/runtime support, including UCRT import libraries and large-frame stack probing.
• Validate Linux arm64/x64/rv64 hosted static and dynamic-executable links.
• Validate freestanding arm64/x64/rv64/rv32 startup, runtime autolink, and no-host assumptions.
• Decide and document target names accepted for the support set (aarch64-*, arm64-*, x86_64-*, riscv64-*, riscv32-*, *-none-elf, *-freestanding, etc.).

Execution environments

Release validation is orchestrated from a macOS/aarch64 host. Prepare each execution environment explicitly so test skips mean "unsupported by this lane", not "runner missing".

Verified native/VM run signoff:

• macOS arm64.
• Windows arm64/x64.
• FreeBSD arm64/rv64/x64.
• Linux arm64/rv64/x64, alpine (musl static and dynamic) and debian (glibc).
• Freestanding arm64/rv64/x64/rv32.

Runtime

• Fill the runtime variant table in mk/rt.mk and driver/lib/runtime.c for every release target.
• Validate compiler-rt integer/fp helpers for every release data model: LP64, LLP64, and ILP32.
• Validate atomic helper coverage, including non-lock-free widths.
• Validate <setjmp.h> and <kit/coro.h> on arm64/x64/rv64/rv32 release variants. Wasm32 has no coroutine support in v1; document that clearly.
• Wire or reject Win64 large-frame probing cleanly.
• Validate runtime header search/install layout for release packages and kit install.
• Add targeted runtime tests for every newly supported FreeBSD/freestanding variant.

RV32

• Finish or clearly reject __int128 on rv32 with a front-end diagnostic.
• Provide or reject 64-bit atomic libcalls (__atomic_*_8) for rv32.
• Legalize 64-bit overflow intrinsics on rv32.
• Fix rv32 i64 varargs.
• Decide and document TLS behavior for freestanding rv32.
• Fix the rv32 soft-float compare lowering bug.
• Triage and fix the 123_spec_demo hang.
• Add rv32 assembler byte-golden lanes and CSR pseudo-op/name coverage, or document the assembler limitation.
• Move rv32 C corpus lanes from known-red/opt-in to release-green, and keep any Toy rv32 lane internal-only rather than part of the release claim.
• Run test-smoke-rv32, rv32 object/link/JIT host-gated tests, and the rv32 parse/codegen corpus under qemu-system-riscv32.

LTO and optimizer

• Merge the LTO work to main without regressing the current build commands, RV32 work, or test layout.
• Keep release optimization levels to -O0 and -O1; LTO must be available at -O1.
• Decide the release spelling (-flto, plus any rejected aliases) and make diagnostics precise.
• Finish link-picture preserved/export set computation for LTO: entry symbol, dynamic imports used by executable links, opaque object/asm references, used, init/fini, IFUNC, address-significant symbols, and visibility.
• Internalize non-preserved globals and re-run whole-module reachability.
• Keep shared-library creation out of scope; make -shared -flto reject cleanly as part of the general dynamic-library creation policy.
• Validate cross-TU inlining and interposition safety on arm64/x64/rv64.
• Add LTO tests for cc, build-exe, build-lib, and build-obj.
• Refresh O0/O1 benchmark baselines and record LTO impact separately.

Build coordinator

• Bring the build-coordinator branch up to current main before merging; avoid losing current build-exe/build-lib/build-obj, RV32, and Wasm work.
• Implement the public surface: <kit/build.h>, KIT_BUILD_ENABLED, KIT_TOOL_BUILD_ENABLED, and kit build.
• Implement the internal modules from the build design: config/argv, definition parser, protocol, trace/deepset, store, remote, coordinator, resolver, runner, bundle import/export, and API composition.
• Keep all build state hanging off explicit coordinator/store/client contexts; no global state.
• Add hermetic tests for byte-stable config/argv/trace/deepset emission and fail-safe parsing.
• Add store crash-safety/fault-injection tests.
• Add minimal-rebuild tests: no-op rebuild, source edit absorbed by a dep, config changes, recipe edits, absent file creation, materialize miss, and diamond deepset sharing.
• Add concurrency tests for jobs limits, future dedup, cancellation, and cycle detection.
• Add kit build CLI smoke tests with real recipes and release packaging integration.
• Move shipped design details from doc/plan/BUILD*.md into durable design docs once implemented; leave only remaining roadmap items in doc/plan/.

WebAssembly and WASI

• Define the exact v1 Wasm target surface: single-TU wasm32, no wasm64, no static Wasm linker, no multi-TU Wasm output.
• Validate wasm32-none single-TU output for C sources and runtime helpers.
• Enable and document partial wasm32-wasi compatibility if accepted for v1.
• Define the supported WASI Preview1 import subset, expected failures, and security policy. At minimum audit argv/env, stdio, proc_exit, random, clock, preopened directories, read/write permissions, and unsupported fd/fs calls.
• Validate kit run Wasm host-import binding, resource policy flags, cwd, env, and exit-code propagation.
• Add Wasm/WASI smoke tests that do not depend on Toy.
• Make unsupported Wasm proposals and unsupported WASI calls fail with feature-naming diagnostics.
• Update doc/WASM.md, doc/plan/WASM.md, driver help, and README to match the v1 Wasm/WASI surface.

Interactive debugger

• Define debugger v1 scope: x64, arm64, rv64 on Linux, macOS, and FreeBSD. Windows and rv32 are explicitly out of scope.
• Validate end-to-end sessions for every supported host/arch pair: breakpoints, continue, step, next, finish, backtrace, registers, variables, memory read/write, Ctrl-C/interrupt, and teardown.
• Bring x64 and rv64 session integration to parity with arm64: fault classification, trap PC normalization, register marshalling, and displaced single-step.
• Add or extend ucontext/register marshalling for FreeBSD x64/arm64/rv64.
• Handle known declined displaced-step forms or diagnose them cleanly.
• Add scripted transcript tests and low-level unit tests for breakpoint patch round-trip, guarded copy, displaced stepping, and source stepping.
• Remove degraded-mode messaging once the v1 session implementation is complete.
• Update doc/DBG.md, doc/plan/DEBUG.md, help text, and README with the exact v1 platform scope.

Linker and dynamic linking

• Preserve executable dynamic-link support: PT_INTERP/PT_DYNAMIC/DT_NEEDED, import libraries, .tbd, and sysroot/library resolution as applicable.
• Reject or hide creating shared libraries for v1 across cc, ld, and build verbs.
• Keep ld -r relocatable combining supported and tested.
• Remove release claims for file-based incremental linking; keep any JIT append/publish internals documented only where they are real and needed.
• Validate executable links against dynamic libraries for Linux, FreeBSD, macOS, and Windows targets in the support set.

C ecosystem gates

• Add a small, curated examples/ or test/ecosystem/ suite that proves kit can compile real C projects with ordinary headers, build scripts, archives, and hosted system libraries.
• Keep the suite deterministic: pinned upstream versions, checked hashes, patch files kept minimal and documented, no network access in default test runs.
• Add a source-built library gate for SQLite: compile the amalgamation, archive libsqlite3.a, build the shell or a focused smoke app, and validate basic SQL execution.
• Add a source-built compression/library gate such as zlib or libpng to cover common configure-style C and archive linking.
• Add a hosted SDL2 gate: compile a minimal C app and link it through the platform mechanism (pkg-config/sdl2-config, framework, or import library), with an offscreen/headless smoke mode where possible.
• Add at least one terminal/system-library app gate, such as ncurses/curses or readline/editline, to exercise hosted include/library discovery.
• Add a macOS framework gate, preferably a pure-C CoreFoundation smoke, to prove -framework and .tbd system-library resolution.
• Add Linux/FreeBSD system-library link gates for -lm, -ldl, -lpthread, and one package-discovered library.
• Add Windows hosted link gates for system/import libraries used by the release support set.
• Run the ecosystem suite at -O0 and -O1; add an LTO lane for at least SQLite once LTO lands.
• Decide which gates are required in default release CI and which are opt-in because they require host packages or graphics/display access.
• Document the examples as supported smoke builds, with exact commands users can run after installing kit.

Release validation

• Reconcile doc/TESTING.md with mk/test.mk so default and opt-in test tiers match reality.
• Define the release CI/test matrix, separating host-independent tests, exec-dependent tests, cross-arch tests, and bootstrap.
• Run targeted frontend tests: test-asm, test-parse, test-pp, test-toy only if still used internally, and Wasm tests.
• Run codegen/API/opt tests: test-cg-api, test-opt, test-isa, test-aa64-inline, x64/rv64 inline tests, LTO tests.
• Run link/object tests: test-link, test-elf, test-macho, test-coff, test-ar, test-driver-ar, test-driver-build.
• Run debug tests: test-debug, test-dwarf, test-dbg, arch-specific dbg tests on supported hosts.
• Run runtime/libc/smoke tests for every supported runtime target.
• Run bootstrap in debug and release modes on the reference host; add other host bootstraps if feasible.
• Run sanitizer/LSan lanes on Linux for driver and library leaks.
• Refresh O0/O1 benchmarks and doc/CODE_SIZE.md.
• Update release packaging: version, licenses, support-dir layout, runtime archives, headers, docs, and kit install default tool set.
• Produce a final release-note feature list and a separate limitations list.