tokra 0.0.1.pre.1

data/doc/contributors/adr/003.md

@@ -0,0 +1,116 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# ADR 003: Tokra Build System & "Ping Pong" Validation
+
+## Status
+Accepted
+
+## Date
+2026-01-29
+
+## Context
+Tokra bridges three distinct ecosystems: Ruby (Gems), Rust (Cargo), and System Libraries (Tao/Wry dependencies like GTK/WebKit).
+A naive implementation using standard `bundle gem --ext` often fails in CI/CD or on user machines because it assumes the presence of Rust toolchains and system headers in non-standard locations.
+
+Furthermore, because Ractors isolate memory state, "classic" Ruby tests (RSpec) that mock objects often produce false positives. They verify logic but fail to verify that objects can actually traverse the Ractor boundary without crashing the VM.
+
+## Decision
+
+### 1. The Build Glue: `rb_sys`
+We will mandate the use of `rb_sys` to normalize the Rust build environment.
+
+* **gemspec:** Must include `spec.add_dependency "rb_sys"`.
+* **extconf.rb:** Must use `create_rust_makefile` to defer compilation to Cargo while respecting Ruby's `mkmf` environment.
+* **Cargo.toml:** Must use `crate-type = ["cdylib"]` to generate a shared object loadable by Ruby.
+
+### 2. The Validation Standard: "The Ping Pong Test"
+
+Before any feature is accepted, it must pass the **Ping Pong Test**. This test verifies the full round-trip capability of the architecture, proving that the Ractor bridge, Main Loop, and IPC are functional.
+
+#### The Test Protocol
+
+1.  **Boot:** Ruby Main Ractor starts.
+2.  **Init:** Rust creates Window & WebView.
+3.  **Frontend Emit:** JS executes `window.ipc.postMessage("PING")`.
+4.  **Rust Bridge:** `Tokra::Native` shareable callback fires (on Main Thread).
+5.  **Port Send:** Main Ractor sends "PING" to Worker Ractor via `Ractor::Port`.
+6.  **Logic Processing:** Worker Ractor appends "PONG".
+7.  **Response Port:** Worker sends response back via response `Ractor::Port`.
+8.  **Proxy Wake:** Worker Ractor triggers `proxy.wake_up()`.
+9.  **Rust Wake:** `Tao` loop wakes, executes callback on Main Thread.
+10. **Frontend Receive:** Main Ractor calls `webview.eval` to send "PINGPONG".
+11. **Verify:** JS assertion confirms receipt of "PINGPONG".
+
+#### Reference Implementation
+
+```ruby
+# test/integration/ping_pong_test.rb
+# frozen_string_literal: true
+
+require "tokra"
+require "timeout"
+
+class PingPongTest < Minitest::Test
+  def test_full_round_trip
+    Timeout.timeout(0.5) do  # 500ms for CI stability
+      # Communication ports (explicit, not default)
+      ipc_port = Ractor::Port.new
+      response_port = Ractor::Port.new
+
+      # Worker Ractor - processes messages and responds
+      worker = Ractor.new(response_port) do |resp_port|
+        msg = Ractor.receive
+        resp_port << (msg + "PONG")
+      end
+
+      event_loop = Tokra::Native::EventLoop.new
+      proxy = event_loop.create_proxy
+      result = nil
+
+      # IPC handler must be shareable
+      ipc_handler = Ractor.shareable_proc do |raw_msg|
+        ipc_port << raw_msg
+      end
+
+      window = Tokra::Native::Window.new(event_loop)
+      webview = Tokra::Native::WebView.new(
+        window,
+        "data:text/html,<script>window.ipc.postMessage('PING')</script>",
+        ipc_handler
+      )
+
+      event_loop.run do |event|
+        case event
+        when Tokra::Native::IpcEvent
+          worker << event.message
+        when Tokra::Native::WakeUpEvent
+          result = response_port.receive
+          webview.eval("window.result = '#{result}'")
+          break
+        end
+      end
+
+      assert_equal "PINGPONG", result
+    end
+  end
+end
+```
+
+**Failure Condition:** If the app hangs, crashes, or times out (>500ms in CI), the build fails. This test MUST run in CI on Linux (headless), macOS, and Windows.
+
+## Consequences
+
+### Positive
+
+* **Reliability:** `rb_sys` handles the complexity of finding `libclang` and linking Ruby headers.
+* **Isolation Verification:** The Ping Pong test proves that objects are actually Ractor-safe (Shareable or Movable), preventing "Works in RSpec, Segfaults in Production" bugs.
+* **Port Ownership:** Using explicit `Ractor::Port` makes message flow clear and prevents accidental cross-Ractor access.
+
+### Negative
+
+* **CI Complexity:** CI runners must have Rust, GTK-dev, and WebKit-dev headers installed.
+* **Timeout Tuning:** The 500ms timeout may need adjustment for slower CI runners or first-run compilation.