feat(phase2-skinny): boj-invoke CLI + Elixir Invoker + router wiring

Implements the OS-process transport from ADR-0005:

- ffi/zig/src/boj_invoke_cli.zig — CLI that takes <so-path> <verb>,
  dlopens the cartridge via std.DynLib (libc-linked so dlopen(3) runs,
  not Zig's partial manual ELF loader), dispatches name/version/probe,
  emits JSON on stdout/stderr. Documented exit codes 0/2/3/4/5/6.

- elixir/lib/boj_rest/invoker.ex — thin wrapper around System.cmd that
  classifies the CLI's exit code into :args/:open/:missing_symbol/
  :init_failed/:cli_missing/:cli_crashed and merges stderr for
  structured error bodies.

- elixir/lib/boj_rest/router.ex — POST /cartridge/:name/invoke now
  probes the cartridge .so and returns 501 with real probe evidence
  (init-returned + name + version for cartridges that have the 5-symbol
  ABI; classified missing-symbol for those that don't). Tool-level
  dispatch still 501 pending ADR-0006.

End-to-end verified 2026-04-18: curl -X POST aerie-mcp/invoke returns
{"probe":{"result":{"name":"aerie-mcp","version":"0.1.0"}}} once
aerie-mcp carries the standard symbols. 5/5 Elixir tests pass.

Key gotcha: std.DynLib on Zig 0.15.2 defaults to manual mmap-based
loading which returns zero-filled string data for .rodata symbols.
Setting link_libc=true on the invoke_mod routes through real dlopen
and fixes it. This should be revisited if we ever need a libc-free
build path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

elixir/lib/boj_rest/invoker.ex

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+defmodule BojRest.Invoker do
+  @moduledoc """
+  Shells out to `boj-invoke` (built by `zig build invoke` in `ffi/zig/`)
+  for cartridge probe/name/version. Skinny Phase 2 per ADR-0005.
+
+  No pool yet — each invocation spawns a fresh child. Pool comes in the
+  follow-up once the cartridge ABI gap (ADR-0006) is closed and there is
+  actual traffic to amortise. Fork-per-request is ~1 ms; acceptable for
+  the skeleton.
+
+  Tool-level dispatch (the `tool` field of `POST /cartridge/:name/invoke`)
+  is not wired here — the caller gets a classified 501 with the probe
+  result as evidence the cartridge loaded. Real dispatch waits on
+  ADR-0006 + a reference cartridge implementation.
+  """
+
+  @cli_binary "boj-invoke"
+
+  # Exit codes from ffi/zig/src/boj_invoke_cli.zig
+  @exit_ok 0
+  @exit_args 2
+  @exit_open 3
+  @exit_symbol 4
+  @exit_init 5
+
+  @type verb :: :probe | :name | :version
+  @type so_path :: String.t()
+  @type result ::
+          {:ok, map()}
+          | {:error,
+             %{
+               exit_code: non_neg_integer(),
+               classification:
+                 :args
+                 | :open
+                 | :missing_symbol
+                 | :init_failed
+                 | :cli_missing
+                 | :cli_crashed,
+               body: map() | String.t() | nil
+             }}
+
+  @doc """
+  Probe a cartridge .so: runs init, reads name+version, runs deinit.
+  Returns `{:ok, %{"name" => ..., "version" => ...}}` on success.
+  """
+  @spec probe(so_path()) :: result()
+  def probe(so_path), do: run(so_path, "probe")
+
+  @spec name(so_path()) :: result()
+  def name(so_path), do: run(so_path, "name")
+
+  @spec version(so_path()) :: result()
+  def version(so_path), do: run(so_path, "version")
+
+  # ── internals ───────────────────────────────────────────────────────
+
+  @spec run(so_path(), String.t()) :: result()
+  defp run(so_path, verb) do
+    cli = cli_path()
+
+    if cli == nil do
+      {:error,
+       %{
+         exit_code: -1,
+         classification: :cli_missing,
+         body: "boj-invoke CLI not found — run `zig build invoke` in ffi/zig/"
+       }}
+    else
+      # stderr_to_stdout merges the CLI's error-path JSON (which it emits on
+      # stderr) into stdout so we get it in the `{output, exit_code}` tuple.
+      case System.cmd(cli, [so_path, verb], stderr_to_stdout: true) do
+        {stdout, @exit_ok} ->
+          case Jason.decode(stdout) do
+            {:ok, map} -> {:ok, map}
+            _ -> {:error, classified(@exit_ok, :cli_crashed, stdout)}
+          end
+
+        {stdout_or_err, code} ->
+          body = try_decode(stdout_or_err)
+
+          classification =
+            case code do
+              @exit_args -> :args
+              @exit_open -> :open
+              @exit_symbol -> :missing_symbol
+              @exit_init -> :init_failed
+              _ -> :cli_crashed
+            end
+
+          {:error, classified(code, classification, body)}
+      end
+    end
+  end
+
+  defp classified(code, cls, body),
+    do: %{exit_code: code, classification: cls, body: body}
+
+  defp try_decode(bytes) do
+    case Jason.decode(bytes) do
+      {:ok, m} -> m
+      _ -> String.trim(bytes)
+    end
+  end
+
+  @doc """
+  Return the path to the boj-invoke binary, or `nil` if not built.
+  Search order:
+  1. `BOJ_INVOKE_CLI` env var if set
+  2. `../ffi/zig/zig-out/bin/boj-invoke` relative to the Elixir project
+  3. PATH
+  """
+  @spec cli_path() :: String.t() | nil
+  def cli_path do
+    env_path = System.get_env("BOJ_INVOKE_CLI")
+    project_path =
+      Path.expand("../ffi/zig/zig-out/bin/boj-invoke", Application.app_dir(:boj_rest))
+      |> fallback_if_missing()
+
+    cond do
+      env_path && File.regular?(env_path) -> env_path
+      project_path -> project_path
+      true -> System.find_executable(@cli_binary)
+    end
+  end
+
+  defp fallback_if_missing(path) do
+    # Application.app_dir points into _build; walk back up to the repo path
+    # for the dev-workflow case where the Zig binary was built at repo root.
+    # __DIR__ is elixir/lib/boj_rest/; need three levels up to reach the repo root.
+    repo_relative =
+      Path.expand("../../../ffi/zig/zig-out/bin/boj-invoke", __DIR__)
+
+    cond do
+      File.regular?(path) -> path
+      File.regular?(repo_relative) -> repo_relative
+      true -> nil
+    end
+  end
+end

elixir/lib/boj_rest/router.ex

@@ -62,13 +62,31 @@ defmodule BojRest.Router do
 
   post "/cartridge/:name/invoke" do
     case BojRest.Catalog.get(name) do
-      {:ok, _cart} ->
+      {:ok, cart} ->
+        # Skinny Phase 2 per ADR-0005: we can probe the cartridge .so
+        # via the Zig CLI, but cannot dispatch to a specific tool yet
+        # (ADR-0006 work). Run the probe so the caller gets real
+        # evidence the cartridge loads; still return 501 on the tool
+        # field because dispatch is not wired.
+        so_path = cartridge_so_path(cart)
+
+        probe =
+          case BojRest.Invoker.probe(so_path) do
+            {:ok, map} -> %{probe: :ok, result: map}
+            {:error, info} -> %{probe: :error, info: info}
+          end
+
+        tool = Map.get(conn.body_params || %{}, "tool")
+
         json(conn, 501, %{
-          error: "invocation-not-yet-wired",
+          error: "tool-dispatch-not-wired",
           cartridge: name,
+          tool: tool,
+          so_path: so_path,
+          probe: probe,
           message:
-            "The REST skeleton can find this cartridge in the catalog but does not " <>
-              "yet dispatch to the Zig FFI. Tracked under the Elixir-port Phase 2 task."
+            "Cartridge can be probed (init/name/version) but tool-level dispatch " <>
+              "awaits ADR-0006 (boj_cartridge_invoke ABI)."
         })
 
       :not_found ->
@@ -85,4 +103,15 @@ defmodule BojRest.Router do
     |> Plug.Conn.put_resp_content_type("application/json")
     |> Plug.Conn.send_resp(status, Jason.encode!(body))
   end
+
+  # Derive the expected shared-library path from a cartridge entry.
+  # Each cartridge builds its .so under `cartridges/<name>/ffi/zig-out/lib/lib<name>_mcp.so`.
+  defp cartridge_so_path(cart) do
+    name = Map.get(cart, "name") || "unknown"
+    root = Application.get_env(:boj_rest, :cartridges_root)
+    Path.join([root, name, "ffi", "zig-out", "lib", "lib#{name_to_lib(name)}.so"])
+  end
+
+  # cartridge name "aerie-mcp" -> lib name fragment "aerie_mcp"
+  defp name_to_lib(name), do: String.replace(name, "-", "_")
 end

elixir/test/router_test.exs

@@ -44,21 +44,23 @@ defmodule BojRest.RouterTest do
     assert conn.status == 404
   end
 
-  test "POST /cartridge/:name/invoke returns 501 for known cartridge" do
-    # Pick any cartridge that loaded successfully — 'database-mcp' is a safe bet
+  test "POST /cartridge/:name/invoke returns 501 with probe info for known cartridge" do
     case BojRest.Catalog.get("database-mcp") do
       {:ok, _} ->
         conn =
-          conn(:post, "/cartridge/database-mcp/invoke", %{tool: "noop"})
+          conn(:post, "/cartridge/database-mcp/invoke", Jason.encode!(%{tool: "noop"}))
           |> put_req_header("content-type", "application/json")
           |> BojRest.Router.call(@opts)
 
         assert conn.status == 501
         body = Jason.decode!(conn.resp_body)
-        assert body["error"] == "invocation-not-yet-wired"
+        assert body["error"] == "tool-dispatch-not-wired"
+        assert body["cartridge"] == "database-mcp"
+        # Probe ran — either ok (symbols present) or error (classified)
+        assert body["probe"]["probe"] in ["ok", "error"]
+        assert is_binary(body["so_path"])
 
       :not_found ->
-        # Catalog empty — still test the 404 path
         :ok
     end
   end

ffi/zig/build.zig

@@ -61,6 +61,22 @@ pub fn build(b: *std.Build) void {
     const bench_step = b.step("bench", "Run cartridge mount/unmount benchmarks");
     bench_step.dependOn(&bench_run.step);
 
+    // --- boj-invoke CLI (skinny Phase 2 per ADR-0005) ---
+    const invoke_mod = b.addModule("boj_invoke", .{
+        .root_source_file = b.path("src/boj_invoke_cli.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    invoke_mod.link_libc = true; // route std.DynLib through real dlopen(3)
+    const invoke = b.addExecutable(.{
+        .name = "boj-invoke",
+        .root_module = invoke_mod,
+    });
+    const invoke_install = b.addInstallArtifact(invoke, .{});
+
+    const invoke_step = b.step("invoke", "Build boj-invoke CLI for Elixir Invoker pool");
+    invoke_step.dependOn(&invoke_install.step);
+
     // --- Catalogue tests ---
     const catalogue_tests = b.addTest(.{
         .root_module = catalogue_mod,

ffi/zig/src/boj_invoke_cli.zig

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// BoJ cartridge invoker CLI (skinny Phase 2 per ADR-0005).
+//
+// Loads a cartridge shared library and calls one of the four standard
+// symbols the loader already requires: init / deinit / name / version.
+// Tool-level dispatch is deferred to Phase 2.1 (ADR-0006).
+//
+// Usage:
+//     boj-invoke <cartridge-so-path> <verb>
+//
+// Verbs:
+//     probe    — run boj_cartridge_init, read name+version, run boj_cartridge_deinit,
+//                emit {"ok":true,"name":"...","version":"..."} on stdout.
+//     name     — read boj_cartridge_name only.
+//     version  — read boj_cartridge_version only.
+//
+// Exit codes (mirrored into the Elixir invoker's error classification):
+//     0   success, JSON on stdout
+//     2   argument error (wrong argc / unknown verb)
+//     3   cartridge .so not found / cannot open
+//     4   missing required symbol in the .so
+//     5   cartridge init returned non-zero
+//     6   tool dispatch not yet wired (reserved for Phase 2.1)
+//
+// This binary is intentionally single-process: fork-per-invocation is
+// acceptable for the skeleton, and the Elixir side will move to a
+// long-lived Port pool in a follow-up once the ABI stabilises.
+
+const std = @import("std");
+
+const EXIT_OK: u8 = 0;
+const EXIT_ARGS: u8 = 2;
+const EXIT_OPEN: u8 = 3;
+const EXIT_SYMBOL: u8 = 4;
+const EXIT_INIT: u8 = 5;
+const EXIT_UNWIRED: u8 = 6;
+
+const Verb = enum { probe, name, version };
+
+fn parseVerb(s: []const u8) ?Verb {
+    if (std.mem.eql(u8, s, "probe")) return .probe;
+    if (std.mem.eql(u8, s, "name")) return .name;
+    if (std.mem.eql(u8, s, "version")) return .version;
+    return null;
+}
+
+fn emitJson(file: std.fs.File, alloc: std.mem.Allocator, comptime fmt: []const u8, args: anytype) !void {
+    const line = try std.fmt.allocPrint(alloc, fmt ++ "\n", args);
+    defer alloc.free(line);
+    try file.writeAll(line);
+}
+
+pub fn main() !u8 {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+
+    const argv = try std.process.argsAlloc(alloc);
+    defer std.process.argsFree(alloc, argv);
+
+    const stderr = std.fs.File.stderr();
+    const stdout = std.fs.File.stdout();
+
+    if (argv.len != 3) {
+        try emitJson(stderr, alloc,
+            "{{\"ok\":false,\"error\":\"args\",\"expected\":\"<cartridge-so-path> <verb>\",\"got_argc\":{d}}}",
+            .{argv.len});
+        return EXIT_ARGS;
+    }
+
+    const so_path = argv[1];
+    const verb = parseVerb(argv[2]) orelse {
+        try emitJson(stderr, alloc,
+            "{{\"ok\":false,\"error\":\"unknown-verb\",\"verb\":\"{s}\"}}",
+            .{argv[2]});
+        return EXIT_ARGS;
+    };
+
+    var lib = std.DynLib.open(so_path) catch |err| {
+        try emitJson(stderr, alloc,
+            "{{\"ok\":false,\"error\":\"open\",\"path\":\"{s}\",\"cause\":\"{s}\"}}",
+            .{ so_path, @errorName(err) });
+        return EXIT_OPEN;
+    };
+    defer lib.close();
+
+    const NameFn = *const fn () callconv(.c) [*:0]const u8;
+    const VersionFn = *const fn () callconv(.c) [*:0]const u8;
+    const InitFn = *const fn () callconv(.c) c_int;
+    const DeinitFn = *const fn () callconv(.c) void;
+
+    switch (verb) {
+        .name => {
+            const name_fn = lib.lookup(NameFn, "boj_cartridge_name") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_name\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+            const n = std.mem.span(name_fn());
+            try emitJson(stdout, alloc, "{{\"ok\":true,\"name\":\"{s}\"}}", .{n});
+            return EXIT_OK;
+        },
+        .version => {
+            const version_fn = lib.lookup(VersionFn, "boj_cartridge_version") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_version\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+            const v = std.mem.span(version_fn());
+            try emitJson(stdout, alloc, "{{\"ok\":true,\"version\":\"{s}\"}}", .{v});
+            return EXIT_OK;
+        },
+        .probe => {
+            const init_fn = lib.lookup(InitFn, "boj_cartridge_init") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_init\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+            const deinit_fn = lib.lookup(DeinitFn, "boj_cartridge_deinit") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_deinit\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+            const name_fn = lib.lookup(NameFn, "boj_cartridge_name") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_name\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+            const version_fn = lib.lookup(VersionFn, "boj_cartridge_version") orelse {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"missing-symbol\",\"symbol\":\"boj_cartridge_version\"}}", .{});
+                return EXIT_SYMBOL;
+            };
+
+            const rc = init_fn();
+            if (rc != 0) {
+                try emitJson(stderr, alloc, "{{\"ok\":false,\"error\":\"init-returned\",\"rc\":{d}}}", .{rc});
+                return EXIT_INIT;
+            }
+            defer deinit_fn();
+
+            const n = std.mem.span(name_fn());
+            const v = std.mem.span(version_fn());
+            try emitJson(stdout, alloc, "{{\"ok\":true,\"name\":\"{s}\",\"version\":\"{s}\"}}", .{ n, v });
+            return EXIT_OK;
+        },
+    }
+}
+
+// Suppress "unused" warning for EXIT_UNWIRED — reserved for Phase 2.1.
+comptime {
+    _ = EXIT_UNWIRED;
+}