kino 0.1.0-aarch64-linux

data/doc/benchmarks.md

@@ -0,0 +1,321 @@
+# Benchmarks: methodology and analysis
+
+The result tables live in the [README](../README.md#benchmarks). This
+document is the part that doesn't fit in a README: how the numbers were
+produced, what they do and don't mean, and the investigations behind the
+odd-looking columns.
+
+The interesting question is not which server is faster—it's what a
+Ractor-based dispatch model buys, and what it costs, relative to the
+battle-tested approaches (Puma's forked workers, Falcon's
+fiber-per-request). Puma is the reference point throughout because it's
+the deployment most apps run today.
+
+## Methodology
+
+- Primary hardware: AWS **c7a.2xlarge**—8 dedicated cores of AMD EPYC
+  9R14 (Genoa), 16 GB RAM, Amazon Linux 2023, kernel 6.18. A realistic
+  app-server size, deliberately: nobody provisions a 32-core box per
+  app process.
+- Toolchain built on the box via mise: Ruby 4.0.5 (**YJIT enabled**,
+  `RUBY_YJIT_ENABLE=1` for every server), Rust 1.96, Kino compiled in
+  the release profile.
+- Load generator: wrk 4.2 on the same host, 8-second windows, 64
+  connections (`bench/run.sh 8 64`). Same-host load generation costs
+  both sides CPU equally; we verified the generator was not the
+  bottleneck by A/B-ing against single-threaded ab, which capped Kino's
+  plaintext 26-37% lower while leaving Puma's number unchanged.
+- Identical app for every server (`bench/bench_app.rb`), Ractor-shareable
+  so Kino's `:ractor` mode can run it unmodified.
+- Topology held equal: Puma 8 forked workers × 3 threads vs Kino
+  8 workers × 3 threads in one process.
+- Follow-up studies (`bench/studies.sh`): CPU recipe, topology sweep,
+  /io worker scaling, logging costs, and memory—run in the same session
+  as the headline tables.
+- The harness waits for the port to be genuinely free between targets.
+  This matters: falcon binds with `SO_REUSEPORT`, so a leftover instance
+  silently splits traffic with the next server and poisons every number
+  after it (we learned this the hard way).
+- Secondary data point: macOS (MacBook Pro, M1 10-core), where every
+  server converges near the loopback ceiling (~42-49k plaintext) and
+  differences compress; its table is at the end of this document.
+  Earlier published numbers from Docker-on-Mac are retired—real
+  hardware contradicted several of that environment's findings, noted
+  inline below where the conclusion changed.
+
+## Reading the headline tables
+
+- **Plaintext/10k**: Kino's tokio front-end clears the fork cluster by
+  1.4-2× (lanes plaintext 241,501 vs Puma 117,838 = 2.05×; the smallest
+  margin is threaded /10k at 1.44×). The cross-ractor handoff shows up
+  as ractor (201k) trailing threaded (218k) on trivial handlers—nothing
+  in them needs parallel Ruby—and lane dispatch reverses that (241k).
+- **CPU (recursive fib)**: ractor mode does **5× its own GVL-bound
+  threaded mode** (66,735 vs 13,298)—that's the entire point of
+  ractors—and beats the fork cluster outright: +15% with stock
+  defaults, +21% with lanes (70,373 vs 58,207).
+- **Memory**: serving the same loaded bench app, Kino held **57 MB
+  (ractor) / 50 MB (threaded)** where the 8-worker cluster held
+  **1,078 MB**—a fork per core pays one full copy of the VM, the app,
+  and its YJIT-compiled code per worker. On the Rails hello-world:
+  Kino 97 MB vs cluster 797 MB.
+- **I/O (5 ms wait)**: all dispatch models tie within ~4% at equal slot
+  counts; the lever that matters is slot count, see
+  [below](#why-io-lags-in-ractor-mode-on-linux).
+
+## CPU-bound tuning
+
+On real hardware, Kino's stock defaults already lead the cluster on
+pure CPU—same-session studies run:
+
+| config | /cpu req/s |
+|---|---:|
+| Puma cluster (reference) | 58,376 |
+| Kino `workers 8, threads 3`, tokio auto (default) | 68,257 |
+| Kino `workers 8, threads 1, tokio_threads 1` (recipe) | 68,629 |
+
+The tuned recipe is a wash (+0.5%)—and it still costs plaintext
+(112,815 vs ~200k) and /io (1,532, 8 slots): on this hardware there is
+no reason to use it. **This is a finding that changed with the
+environment**: in the earlier Docker-on-Mac runs the recipe was worth
++12%, because tokio threads and wake churn competed for oversubscribed
+virtualized cores. If you deploy into a constrained/virtualized
+environment, the recipe may still pay; measure there.
+
+Two findings that survived the environment change:
+
+**Ruby executes at identical per-core speed in ractors and forks.** We
+briefly believed parallel ractors paid a ~24% execution tax; that probe
+compared 8 busy ractors against a *single* busy thread, which also
+compares all-core clocks against single-core boost. The controlled probe
+(8 forked processes vs 8 ractors, same all-core clock): forks 8,973
+fib/s/core, ractors 8,918—identical. `GC.disable` changes nothing (fib
+barely allocates). The VM is innocent. Never compare parallel against
+single-threaded baselines without controlling for clocks.
+
+**The GVL ceiling is absolute.** Threaded mode posts the same ~13k /cpu
+whatever the topology—24 threads in one process serialize on one lock.
+Parallelism for CPU-bound Ruby comes from ractors or forks, nothing else.
+
+## Why /io lags in ractor mode on Linux
+
+On bare metal the gap is small: ractor /io 4,527 vs threaded 4,715
+(−4%). In Docker it was −18%, and a pure-Ruby probe there measured
+`sleep(0.005)` waking +2.3-2.8 ms late inside ractors vs +1.8 ms on the
+main ractor—non-main-ractor timer wakeups are coarser in Ruby 4.0, but
+how much that costs depends heavily on the kernel/virtualization stack.
+A follow-up probe showed `IO.select`-style waits are tighter than
+`sleep` inside ractors, so real I/O readiness suffers less than timers.
+
+**Mitigation 1—`Kino.sleep`:** releases the GVL and waits on the OS
+clock directly (chunked, so `Thread#kill`/shutdown stay responsive). The
+`/io_native` endpoint (same 5 ms wait via `Kino.sleep` when available)
+erases the remaining ractor gap on this box: 4,714 vs 4,527 plain sleep.
+
+**Mitigation 2—add workers; they're nearly free.** Wait-bound
+throughput is simply `slots ÷ effective wait`, and Kino's slots cost ~a
+thread each, not a forked process: `workers 32, threads 1` measured
+**5,922 /io (+27% over the 24-thread cluster's 4,672) and 6,254
+/io_native (+34%)**, still one small process. A fork cluster buying the
+same 32 slots pays for them in full copies of the app.
+
+## The ractor-pool-wrapper comparison
+
+A reasonable first experiment for anyone curious about ractors is a Rack
+wrapper that ships each request to a ractor pool on whatever server they
+already run. `bench/ractor_wrapper.rb` is that experiment, benchmarked on
+Puma and Falcon—not as a comparison of those servers, but to measure
+what the Rack-level hop itself costs (c7a.2xlarge, same session):
+
+| endpoint   | Kino :ractor | Puma + wrapper | Falcon + wrapper |
+|------------|-------------:|---------------:|-----------------:|
+| /plaintext |      201,472 |         19,425 |          100,624 |
+| /cpu (fib) |       66,735 |         17,106 |           49,083 |
+| /io (5 ms) |        4,527 |          1,447 |            1,549 |
+
+Inside the Rack contract, the wrapper must reduce the env to a shareable
+subset, copy it to the worker ractor, copy the response back, and hold a
+server thread for the round trip—that's the 10× gap in the Puma
+column, and it would be the same for any server in that position. The
+Falcon numbers mostly show its per-core forks doing the work (the
+per-fork ractor adds little), while `Port#receive` blocking its event
+loop is what limits the I/O endpoints—ractors and fiber schedulers
+don't compose yet, which is a Ruby-level limitation, not a Falcon one.
+Our conclusion: ractor dispatch needs to live at the server layer, below
+the Rack contract—which is the experiment this gem exists to run.
+
+## Rails
+
+The example app (`examples/rails-hello`, edge Rails, production mode,
+8 workers × 5 threads) on the same box:
+
+| | req/s | RSS under load |
+|---|---:|---:|
+| Kino `:threaded` (one process) | 2,298 | **97 MB** |
+| Puma cluster (8 workers) | 11,923 | 797 MB |
+
+This is the honest version of the Rails story: in threaded mode Kino is
+one GVL-bound process, so the fork cluster outruns it ~5× by using all
+8 cores—at 8× the memory. Rails-on-Ractors is interesting precisely
+because it would close that throughput gap at the one-process memory
+cost; the upstream blockers are documented in
+[rails-on-ractors.md](rails-on-ractors.md).
+
+## YJIT × Ractors gotcha (found the hard way)
+
+Plain `def` methods get the full YJIT speedup inside worker ractors
+(5.8× in our probe—YJIT + Ractors compose fine in Ruby 4.0). But a
+**self-referential lambda** (`fib = ->(x) { ... fib.call(x - 1) ... }`)
+runs *slower* with YJIT than without when shared across parallel
+ractors. Keep hot-path code in methods (which real apps do anyway); our
+own /cpu benchmark was a victim of this pattern until it wasn't.
+
+## Rust-side allocator: mimalloc
+
+The native extension's global allocator is **mimalloc**, unconditionally.
+It covers all Rust-side allocations—request/response buffers, hyper,
+tokio, channels—not the Ruby heap. The decision came from a three-way
+shoot-out (measured in the earlier Docker-on-Linux environment, one
+container session):
+
+| allocator | /plaintext | /10k | /cpu |
+|-----------|-----------:|-----:|-----:|
+| system (glibc) | 131,978 | 114,121 | 45,690 |
+| **mimalloc** | **145,229** | 113,907 | 45,351 |
+| jemalloc | 134,632 | 111,341 | 47,273 |
+
+mimalloc won plaintext by ~10% with everything else flat, with no
+downside measured. For the record, jemalloc inside a Ruby extension also
+needs its `disable_initial_exec_tls` build flag just to load (dlopen +
+initial-exec TLS = `cannot allocate memory in static TLS block`)—one
+more reason to prefer mimalloc in dlopen'd extensions.
+
+## Run-to-run variance (a.k.a. "is this a regression?")
+
+Rule of thumb from chasing this twice: never compare numbers from
+different sessions; interleave A/B rounds in one session instead. The
+Docker-on-Mac environment swung ±10% on /cpu between sessions with the
+VM's mood; the dedicated c7a box is far steadier (same-session repeats
+land within ~1-2%), but the discipline stays—every comparative claim in
+these docs comes from same-session pairs.
+
+## Topology notes
+
+Measured on c7a.2xlarge, plaintext, ractor mode, same session: `8×3`
+(workers×threads) = 199,470, `8×1` = **232,469 (+17%)**, `16×1` =
+214,284. Threads inside one ractor share its lock, so every request
+handled by a 3-thread ractor pays a lock handoff that a 1-thread ractor
+doesn't (`perf` in the earlier Docker sessions attributed ~10% of cycles
+to `rb_native_mutex_unlock`/`thread_sched_wakeup_next_thread` at 8×3;
+the +17% reproduces exactly on real hardware). Threads-per-ractor exist
+for handlers that block on I/O; if yours don't, run `threads 1` and let
+workers = cores do the parallelism. (16×1 being worse than 8×1 also says
+the shared MPMC queue is *not* the bottleneck—8 extra parked consumers
+just add scheduler churn.)
+
+## What profiling tried and rejected
+
+A perf profile of saturated plaintext showed ~20% of cycles in futex
+wakeups: at saturation the queue oscillates around empty, so nearly every
+request parks its worker and pays two wake round-trips (tokio firing the
+channel signal + the GVL reacquire). The textbook fix—a bounded
+busy-poll before parking—measured **worse** (-13% on both modes): with
+workers + tokio threads oversubscribing the cores, spinners steal exactly
+the CPU the event loop needs. Parking is the cheaper evil when threads
+outnumber cores; the fix that did land is the fused
+`respond_and_take` call (answer the previous request and block for the
+next in one FFI crossing) plus the opt-in `batch` directive for grabbing
+several queued requests per visit (default 1—values above 1 add
+head-of-line blocking behind slow handlers and stretch effective queue
+depth, which is also why it's a config knob and not a hardcoded win).
+
+## Lane dispatch (experimental: `lanes true`)
+
+The shared-queue design pays a futex wake per request at saturation
+(every worker parks on an empty queue between requests). Lane mode gives
+each worker a small private queue; the dispatcher prefers *awake* lanes—so
+a hot worker keeps taking without ever being woken—with two
+safeguards: lane depth is capped at 4, and workers steal from siblings
+before parking (plus on every park tick), so a slow request can't strand
+its lane's backlog.
+
+Same-session A/B on c7a.2xlarge (ractor mode):
+
+| endpoint | shared queue | lanes | delta |
+|----------|-------------:|------:|------:|
+| /plaintext | 201,472 | **241,501** | **+20%** |
+| /10k | 156,635 | 183,564 | +17% |
+| /cpu | 66,735 | 70,373 | +5% |
+| /io | 4,527 | 4,530 | flat |
+
+On this hardware lanes make ractor mode the fastest Kino configuration
+outright—+11% over threaded mode's plaintext, where the shared queue
+trails it. (On loopback-bound macOS, lanes lose a few percent instead;
+see the secondary table below.) It stays opt-in for now because overload
+semantics differ from the shared queue (`queue_depth` doesn't apply;
+capacity is lanes × 4 with brief dispatcher retries up to
+`queue_timeout` before the 503), and crash semantics, stealing fairness,
+and drain behavior have spec coverage but not production mileage.
+
+## Logging costs
+
+Measured at full plaintext saturation (one log line per request—rates
+that no real deployment logs at; treat these as worst-case ceilings, not
+typical costs):
+
+| case (8×3, same session) | req/s |
+|---|---:|
+| threaded, no logging | 217,113 |
+| threaded, `log_requests true` (native access log) | 193,200 (−11%) |
+| ractor, access log off / on | 198,624 / 183,565 (−8%) |
+| app logs 1 line/req via shared `::Logger` (file) | **62,962** |
+| app logs 1 line/req via `Kino::Logger` (file) | **150,810 (2.4×)** |
+
+The shared-`::Logger` cost is the mutex: 24 worker threads serialize
+through one lock plus a write syscall per line. `Kino::Logger` hands the
+formatted line to a lock-free channel and returns—the remaining cost vs
+not logging at all is Ruby-side formatting, which no device can remove.
+(In the Docker environment the same comparison showed 8.5×—overlay-fs
+write latency punished the synchronous logger far harder than this box's
+NVMe does. The ranking is environment-independent; the multiple is not.)
+
+One trade-off worth knowing: the sink **never blocks** request threads,
+so at absurd rates against a slow disk it drops lines once its 8192-line
+buffer is full, while `::Logger` writes every line by strangling
+throughput instead. Pick your failure mode; at sane logging rates
+neither happens.
+
+Puma comparison note: request logging is opt-in there too (`--quiet` is
+the default, `-v/--log-requests` enables it)—Kino's default-off
+`log_requests` matches the ecosystem's standard behavior.
+
+## Hot-path notes
+
+For the curious, the dispatch-path work behind the numbers: a try-pop
+fast path skips the GVL release when a request is already queued,
+bodyless requests spawn no body-forwarder task, `TCP_NODELAY`, a frozen
+(Ractor-shareable) cache of env keys + common header names built once at
+init, response headers read in place across the FFI boundary, ahash for
+per-request lookups, SmallVec for header joins. Details in
+[architecture.md](architecture.md).
+
+## Secondary data point: macOS
+
+MacBook Pro (M1 10-core), ab with keep-alive, 10 workers × 3 threads.
+Everything converges near the loopback ceiling and differences compress;
+useful mainly as a sanity check that the ranking holds on a second OS:
+
+| endpoint    | Kino :ractor | + lanes | Kino :threaded | Puma (cluster) |
+|-------------|-------------:|--------:|---------------:|---------------:|
+| /plaintext  |       48,441 |  44,000 |         49,352 |         44,594 |
+| /10k        |       45,840 |  42,362 |         46,482 |         42,890 |
+| /cpu (fib)  |       43,827 |  41,426 |         10,076 |         34,161 |
+| /io (5 ms)  |        4,943 |   4,883 |          4,890 |          4,780 |
+| /io_native  |        4,758 |   4,844 |          4,848 |          4,805 |
+
+Notes from this environment: lanes lose a few percent (the loopback
+stack, not dispatch, is the ceiling); macOS loopback occasionally stalls
+entire benchmark windows under back-to-back runs (the harness sleeps
+between endpoints to reduce this; treat any isolated collapsed cell as
+suspect and re-run); the ractor /cpu margin over the cluster (+28%) is
+wider than on Linux because macOS Puma forks pay a higher per-fork cost.

data/doc/rails-on-ractors.md

@@ -0,0 +1,50 @@
+# Rails on Kino, and the state of Rails-on-Ractors
+
+`examples/rails-hello` runs edge Rails on Kino.
+
+## What works as of Kino 0.1.0: `:threaded` mode
+
+Rails 8.2.0.alpha boots and serves with `mode :threaded` (see the
+example's `kino.rb`; just `bundle exec kino` in that directory). Measured
+on the hello-world (c7a.2xlarge, 8 cores, production mode, 8×5):
+~2.3k req/s in 97 MB, single process. The 8-worker Puma cluster reaches
+~11.9k in 797 MB by parallelizing across forks—Rails-on-Ractors is
+interesting precisely because it could offer that ~5× parallelism at
+~1/8th of the memory.
+
+Pair it with production-style Rails settings: eager load, no code
+reloading, database pool ≥ workers × threads, logger to stdout or another
+thread-safe device.
+
+## What doesn't (yet): `:ractor` mode—with the exact blockers
+
+`examples/rails-hello/ractor_probe.rb` re-tests this against whatever
+Rails is bundled; when it prints SUCCEEDED *and* a 200 ractor-mode
+response (sharing the app is only the first blocker), flip
+`mode :ractor`. As of June 2026 (rails main):
+
+1. **Sharing the booted app fails.**
+   `Ractor.make_shareable(Rails.application)` raises
+   `Ractor::IsolationError: Proc's self is not shareable` at
+   `railties/lib/rails/application/finisher.rb:151`—a routes-reloader
+   hook lambda Rails registers at boot (in the development path) whose
+   `self` is the unshareable application instance.
+2. **Calling the app from a worker ractor fails** even where
+   `make_shareable` succeeds on a class:
+   `Ractor::IsolationError: can not get unshareable values from instance
+   variables of classes/modules from non-main Ractors (@instance from
+   HelloApp)`—`Rails.application` is a class-level ivar read on the
+   dispatch path.
+3. **Every workaround is closed by one VM rule** (verified on Ruby 4.0.5):
+   class instance variables are main-ractor-only—non-main ractors can
+   neither read them (when the value is unshareable) nor set them, **even
+   inside a `Ruby::Box`** (`RUBY_BOX=1`). Box isolates constant tables,
+   but Ractor isolation still applies to box-local classes:
+
+   ```
+   Ractor::IsolationError: can not set instance variables of
+   classes/modules by non-main Ractors
+   ```
+
+   So booting a private Rails per worker ractor (boxed or not) dies on
+   the first class-ivar write, and sharing one boot dies on reads.

data/doc/why-kino.md

@@ -0,0 +1,91 @@
+# Why Kino is a Ractor server
+
+What makes this server ractor-specific, why do Ractors work fast here
+when they are slow everywhere else, and which Rust parts deserve the
+credit. Companion to [architecture.md](architecture.md), which describes
+the same machinery piece by piece.
+
+## The problem Kino exists to solve
+
+Ractors forbid sharing mutable Ruby objects. That single rule breaks
+every conventional server design. Puma hands env Hashes, socket objects,
+and request state between threads freely; with Ractors, a Ruby object
+created on the accepting side cannot be given to a worker—`Ractor#send`
+deep-copies it, and sockets cannot cross at all.
+
+We measured what the "obvious" workaround costs. The ractor-pool wrapper
+experiment (reduce the env to a shareable subset, copy it to a worker
+over a `Ractor::Port`, copy the response back) runs at **19k req/s where
+Kino does 201k** on the same hardware—see the
+[wrapper comparison](benchmarks.md#the-ractor-pool-wrapper-comparison).
+Copying at the Rack layer eats the entire ractor dividend. Dispatch has
+to live below the Rack contract.
+
+## The trick: shared state lives below the FFI line
+
+Kino's answer is that **the request never exists as a Ruby object until
+it is already inside the worker ractor**. The whole request—method, URI,
+headers, body stream, response channel—lives in native memory as a Rust
+`RequestCtx`. The only things that cross ractor boundaries in Ruby are
+what Ractor law allows for free: integers (server id, worker ids) and
+the frozen, shareable app. When a worker calls `take_one`, the env Hash
+and the `Kino::Native::Request` handle are *constructed inside that
+worker's ractor*—ownership is correct by construction, nothing is
+copied, nothing is shared.
+
+Put differently: Ractors cannot have shared mutable memory in Ruby, so
+Kino moves all shared mutable state into Rust, where `Send`/`Sync` rules
+apply instead of ractor isolation. Ruby sees only ids and frozen
+objects; Rust sees one queue and one registry.
+
+## The Rust parts to thank, in order of credit
+
+1. **`rb_ext_ractor_safe(true)`** (lib.rs)—one line, and the
+   precondition for everything: without it, *any* native call from a
+   non-main ractor raises `Ractor::UnsafeError`. The spec suite keeps a
+   canary test on this.
+2. **The registry** (registry.rs)—global Rust-side state keyed by
+   `u64`. This is the "shared memory" Ractors legally cannot have:
+   workers address everything by integer, and no TypedData object ever
+   crosses a boundary.
+3. **The flume MPMC queue**—the cross-ractor work distributor. One
+   queue, async send from tokio, blocking receive from any ractor's
+   thread. Ruby has no ractor-safe equivalent that does not copy
+   (Ports copy every message); a Rust channel moves a
+   `Box<RequestCtx>` pointer.
+4. **`gvl.rs`**—`rb_thread_call_without_gvl` plus the atomic-flag UBF
+   idiom. A worker blocking on the queue releases its per-ractor lock,
+   stays interruptible (Thread#kill, shutdown) via bounded
+   `recv_timeout` ticks, and costs nothing when the queue has work: the
+   `try_recv` fast path skips the lock release entirely.
+5. **The frozen env-string cache** (env_strings.rs)—exploits the one
+   sharing channel Ractors *do* allow: frozen objects. Env keys, 44
+   common header names, methods, LRU'd host and peer-address values,
+   built once on the main ractor and read by every worker forever.
+   Without this, each ractor would allocate every key on every request.
+6. **The Responder** (response.rs)—responses travel back as Rust types
+   through a oneshot/frame channel into hyper, never as shared Ruby
+   objects. Its first-claimant atomic is also what makes crash recovery
+   work: the supervisor (on the main ractor) can 500 a dead ractor's
+   in-flight requests through `Weak` references into native memory.
+   That cross-ractor cleanup would be impossible if request state were
+   Ruby-side.
+7. **tokio + hyper owning all I/O**—sockets are exactly the kind of
+   unshareable object that poisons ractor designs; here Ruby never
+   touches one.
+
+## Why it is fast, by the numbers
+
+With the dispatch cost eliminated, Ractors deliver the thing they were
+built for—a lock per ractor instead of one GVL—and each layer is
+visible in the [benchmarks](benchmarks.md): `/cpu` at 66.7k req/s in
+ractor mode vs **13.3k threaded (5×, the GVL ceiling)**, matching the
+fork cluster's CPU parallelism while holding **57 MB against the
+cluster's 1,078 MB**, because eight ractors share one VM, one Rust
+front-end, one queue, and one JIT, where eight forks each pay full
+price.
+
+The cleanest proof of the design is the threaded fallback itself: it
+reuses ~95% of the same machinery, because the Rust core is
+dispatch-agnostic. Ractors are not what makes Kino's engine fast—they
+are what the engine finally makes *usable*.

data/exe/kino

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# kino [-C config.rb] [rackup_file]
+#
+# Boots a Rack app from a rackup file (default: config.ru) with settings
+# from a Puma-style Ruby DSL config file (default: kino.rb if present).
+# All the real work lives in Kino::CLI.start; this file only sets up the
+# process-global bits an executable owns.
+
+Warning[:experimental] = false
+# Startup output must land immediately even when stdout is a pipe or file
+# (process supervisors, `kino > server.log`); block buffering would hold
+# the banner back until exit.
+$stdout.sync = true
+
+# Running from a git checkout (no installed gem, no bundler context):
+# prefer the checkout's own lib so `require "kino"` resolves.
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(File.join(lib, "kino")) && !$LOAD_PATH.include?(lib)
+
+# cli.rb loads no native code: --help and --version stay instant; the
+# compiled extension loads only when a server actually boots.
+require "kino/cli"
+
+exit Kino::CLI.start(ARGV)