write-elixir

write-elixir

Write Elixir for the project. The standard is skills/write-elixir/references/elixir-style.md (read it first). The architecture it implements is Functional Core / Imperative Shell; the Elixir expression of that split, and the native boundary contract, live in skills/shared/references/architecture.md. Placement follows the module map (the :architecture :modules entry in the descriptor). The why behind the constraints is the ADR log: scan it before designing against an unexplained rule.

The Elixir expression of the split maps cleanly onto OTP. The pure core is pure functions in modules: they take data (maps, structs, tuples) and return data, do no IO, send no messages, hold no state. Pattern matching and the immutability guarantee do the work the GC does in C and the allocator does in Zig. The imperative shell is GenServers and OTP: processes that hold state, receive messages, talk to the disk and the network. The shell calls the pure core from inside handle_call, handle_cast, and handle_info, and applies the return as the new process state plus any side effects.

Procedure

1. Place it. Find the owning module from the module map. Pure logic goes in a plain module of functions; a process that holds state, receives messages, or touches the world goes in a GenServer (or the fitting OTP behaviour) under the shell. A function that needs a PID to make sense does not belong in the core.
2. Elixir discipline. The load-bearing rules:
   • Pure core has no process identity. A core function does not know the PID it runs in; it does not send or receive, it does not read or write the process dictionary, it does not consult the clock. Testing the core is calling it: data in, data out, no setup ceremony.
   • GenServer and OTP are the shell. State, timers, IO, and messaging live in GenServers, Agents, Tasks, and the supervisors that own them. The shell calls the core from a callback and applies the return: the new state from the pure result, the side effects the result describes. The shell carries no logic of its own; it switches on the tagged tuple the core returns.
   • Supervision trees own lifecycle. The shell is a tree of supervisors and workers; the restart strategy (one_for_one, one_for_all, rest_for_one) is explicit and chosen for what a crash invalidates. Pure functions never start or stop processes. A worker and its supervisor land together; a worker without a place in the tree is incomplete.
   • Errors as tagged tuples in the core; let-it-crash at the edge. The core returns {:ok, value} or {:error, reason} tuples a caller branches on with with; it does not raise. The shell raises on programmer error and lets the supervisor restart on runtime failure, because the supervision tree is the recovery strategy.
   • NIF boundary discipline. When a NIF calls C or Zig, the native boundary contract in skills/shared/references/architecture.md applies unchanged: data in, data out, opaque handles, explicit lifetime, errors as values. A NIF is the shell of last resort: only when the BEAM cannot meet the requirement, never as a default. A NIF that blocks the scheduler runs dirty, and that decision is written down next to the loader.
3. Failure model. The core returns tagged tuples for expected failure and raises only for programmer error (a violated precondition the caller controls). The shell trusts the supervision tree for runtime failure: a crashed worker restarts into a known-good state, and the tree's restart intensity bounds a crash loop. Untrusted input (bytes from the network or disk, a payload that crosses the NIF edge) is validated before it reaches the core and rejected as data when malformed.
4. Verify like the lanes. The project's cheap lanes from the descriptor: mix format --check-formatted, mix compile --warnings-as-errors, mix test. For NIF or native-edge code, run the integration lane that builds the native side, loads it, and calls it with both a known-good and a malformed input. If you wrote process or supervision code, run the suite that starts the tree and tears it down, so a leak or a missing child fails the test.