initial github workflow

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "showcase",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["--prefix", "content/showcase", "run", "dev", "--", "--port", "5173"],
+      "port": 5173
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  LLVM_SYS_211_PREFIX: /usr/lib/llvm-21
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install LLVM 21
+        run: |
+          wget -q https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          sudo ./llvm.sh 21
+          sudo apt-get install -y llvm-21-dev liblld-21-dev libclang-21-dev ripgrep
+          rm llvm.sh
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - run: ./test.sh
+
+      - name: Binding drift from module setups
+        if: failure()
+        run: git --no-pager diff --stat && git --no-pager diff modules/ | head -400

CLAUDE.md

@@ -52,11 +52,13 @@ K1 language reference for agents: `ai_docs/k1-syntax-basics.md` and
 - Binaries: `k1` (`src/bin/compiler_main.rs`), `k1_test`
   (`src/bin/test_suite.rs`), `lsp` (`src/bin/lsp_main.rs`, needs
   `--features lsp`).
-- CLI: `k1 [flags] <check|build|run|test|server|setup|clean> [path]`, aliases
-  `c b r t`. Path is a file or a module dir. Useful flags: `--optimize`,
-  `--debug`, `--no-std`, `--cache false`, `--target <intel64-linux|arm64-macos|
-  wasm64-wasi|intel64-bare|arm64-bare|wasm64-bare>`, `--emit-llvm`,
-  `--dump-module`, `--dump-trace`, `--chatty true` (timing summary), `--filc`.
+- CLI (`k1 --help`, lexopt): `k1 <check|build|run|test|server|setup|clean>
+  [path] [flags] [-- program args]`, aliases `c b r t`; flags go anywhere.
+  Path is a file or a module dir. `-D name[=value]` reaches the primary's
+  `fn build`. Useful flags: `--optimize`, `--debug`, `--no-std`, `--no-cache`,
+  `--target <intel64-linux|arm64-macos|wasm64-wasi|intel64-bare|arm64-bare|
+  wasm64-bare>`, `--emit-llvm`, `--dump-module`, `--dump-trace`, `--chatty`
+  (timing summary), `--filc`.
 - Output goes to `<module dir>/.k1-out/` (executable, `.ll`, dumps, disk cache
   under `cache/`, setup stamps under `setup/`).
 
@@ -89,11 +91,19 @@ for compile-time execution, codegen_llvm for binaries.
 
 - `lib.rs`: crate root, `nz_u32_id!` id newtypes, `SV2/4/8` smallvec aliases,
   `DepHash/DepEq`.
-- `compiler.rs`: CLI `Args`/`Command`, `CompilerConfig`, `Target` = arch x
-  platform enum, module discovery (`module.k1` or `<dir>/<dir>.k1` root),
-  source reading and lexing on reader threads, setup stamps, disk cache
-  restore, linking through `src/lld_shim.cpp`, running compiled programs,
-  `static_assert_size`/`static_assert_niched`, `compiler_test`.
+- `compiler.rs`: `CompileRequest` (the compile API; the CLI in `compiler_main.rs`
+  builds one), `Command`, `ToolFlags`, `CompilerConfig`, `BuildConfig` (target,
+  cpu, features, flags; one resolver), `Target` = arch x platform enum, the
+  compile pipeline (plan, up-front source reads on reader threads, prefix
+  snapshot restore), setup stamps, linking through `src/lld_shim.cpp`,
+  running compiled programs, `static_assert_size`/`static_assert_niched`,
+  `compiler_test`.
+- `plan.rs`: `BuildPlan` (config + modules in dependency order, libs, link
+  args, setups, dep-params providers), dep lookup, the plan cache and its
+  freshness check. Strings are `StringId`s in the plan's own `Interner`.
+- `typer/host.rs`: the host world H that compiles every `build.k1` against
+  host core+std, runs `fn build`/`fn module`/`fn setup` in waves, and produces
+  the plan.
 - `kpath.rs`: paths are canonical UTF-8 strings interned in the ident pool;
   `std::path` only at OS call sites.
 - `lex.rs`: positional lexer, `Token`, `Span`/`SpanId`, trivia side table.
@@ -116,27 +126,35 @@ for compile-time execution, codegen_llvm for binaries.
   - `typer/snapshot.rs`: `TypedProgram` <-> `snap` serialization, inputs hash.
   - `typer/trace.rs` + `report.rs`: the compile work-stack trace, timing
     summaries, diagnostics printing.
-  - `typer/dump.rs`: `--dump-module` text form. `typer/visit.rs`: expr
-    walkers. `typer/typed_int_value.rs`: integer constants.
+  - `typer/dump.rs`: `--dump-module` text form. `typer/typed_int_value.rs`:
+    integer constants.
   - `typer/megarepl.rs`: cells/widgets model behind `k1 server`.
   - `typer/derive.rs`: `unimplemented!` stub.
 - `ir.rs` + `ir/iropt.rs`: typed exprs -> SSA `IrUnit`s per function, IR
   optimization and inlining.
+  - `ir/unit.rs`: unit storage. Inst and block ids are unit-local indices;
+    passes edit a pooled `UnitBuf` (linked layout, preds), `commit_unit`
+    compacts it into layout order and stores it as arena slices on the
+    `Copy` `IrUnit`; every reader takes a `UnitView`. Call, phi, switch,
+    cmpxchg and vec-op payloads are per-unit arrays.
 - `bc.rs` + `bc/{lower,exec,disasm}.rs`: flat bytecode lowered from IR, the VM
   that runs compile-time code, disassembler.
 - `vm.rs` + `vm/vm_ffi.rs`: VM memory model, `k1_types` mirrors of K1
   runtime structs, libffi calls into native libs and dlsym'd externs.
 - `codegen_llvm.rs`: inkwell LLVM backend, parallel codegen units, ThinLTO
   via `src/thinlto_shim.cpp`.
-- `snap.rs`: memory snapshot format (`SNAP_MAGIC` version) for the disk cache
-  and LSP restores. Bump the magic when pooled layouts change.
+- `snap.rs`: memory snapshot format for the disk cache and LSP restores. The
+  header carries `BUILD_ID`, which already invalidates every snapshot when
+  `src/` changes; `SNAP_MAGIC` needs no bump.
 - `kmem.rs`: the never-freed arena (`Mem`, `List`, `Dlist`, handles) most
   compiler data lives in. `vpool.rs`/`vecpool.rs`: id-indexed pools.
   `fixmap.rs`, `rawref.rs`, `unique_stack.rs`, `clock.rs`: small utilities.
 - `server.rs` + `server/`: `k1 server`, the megarepl web app (HTTP, SSE bus,
   program browser, `/size` code-size treemap; `megarepl.css`, `size.js`).
 - `lsp_support.rs` + `src/bin/lsp_main.rs`: hover/goto/completion over
-  `ls_entities`, compiles the edited file's module.
+  `ls_entities`, compiles the edited file's module with the client's
+  `k1.build` setting (`k1/build-config` fields plus `options`); `build.k1` errors come
+  back from H.
 - Not compiled: `codegen_legacy.rs.old`, `vmtw/binop.rs` (`vmtw` is commented
   out in `lib.rs`).
 
@@ -146,7 +164,7 @@ for compile-time execution, codegen_llvm for binaries.
   `//errmsg: <substring>`, `//exitcode: <n> [stderr substring]`,
   `//abortmsg: <substring>`, else exit 0.
 - `test_src/<dir>/`: module cases (`suite1`, `stdlib`, `ffi_abi_test`,
-  `dep_*_test`). `k1_test` runs every top-level file and dir in parallel; it
+  `dep_*_test`). `k1_test` runs every top-level file and dir in parallel (`--serial` for one at a time); it
   does not recurse.
 - `test_src/suite1`: ~110 files, each `ns foo` with `fn test()`, registered by
   hand in `suite1.k1` (`low`, `moderate`, `core-lib`, `main`). Nearly every
@@ -158,10 +176,13 @@ for compile-time execution, codegen_llvm for binaries.
 
 ## Modules (`modules/`)
 
-A module is a dir with `module.k1` (or `<name>/<name>.k1`). `module.k1`
-holds `ns build { fn module(): k1/module }` declaring `dep`, `lib`, `library()`
-and an optional `setup` fn that runs in the VM (cwd = module dir) when its
-declared inputs are newer than the `.k1-out/setup/stamp`.
+A module is a dir with `build.k1`, `module.k1` or `<name>/<name>.k1`.
+`build.k1` is compiled on the host before the program: optional `fn build(req)`
+(primary only; edits `req.default`, reads `-D` options), `fn module(b)`
+declaring `dep`/`dep-params`, `lib`, `library()`, `setup`, and an optional
+`fn setup(ctx)` that runs (cwd = module dir) when its stamp in
+`.k1-out/setup/stamp` is stale. Deps resolve through `<primary>/deps/y`,
+`<dependent>/deps/y`, then `$K1_HOME/modules/y`.
 
 - `core/`: always loaded. `builtin.k1` (scalar aliases, `buffer`/`span`/
   `list`/`string`/`opt`/`result`, `types`, `meta`, every core ability: