feat(orchestrator-lsp-mcp): Steps 1-3 — Elixir adapter, Zig FFI, ReScript VSCode extension

Step 1: Elixir GenLSP adapter (adapter/)
- Application supervisor with GenLSP LSP server
- Domain planner routes by file extension and workspace path
- Fan-out executor uses Task.async_stream with 5 s timeout
- Handlers: completion (merge+tag), hover (domain headings), diagnostics (prefix)
- Stack parser reads .machine_readable/integrations/*.a2ml; 12-domain port fallback
- LSP client pool registry (domain → pid)
- VeriSimDB client: session record/close via :httpc, graceful :unavailable
- 41 ExUnit tests across planner, stack_parser, completion, hover

Step 2: Zig FFI (ffi/zig/)
- Full ADR-0006 five-symbol ABI: init/deinit/name/version/invoke
- Session table: MAX_SESSIONS=8 with workspace_root and 12-domain bitset
- lsp_orchestrate_start/stop managed in Zig (no port needed)
- lsp_orchestrate_request/status delegate to Elixir adapter via Erlang
  port protocol (4-byte BE framing, single mutex for full round-trip)
- Lazy port spawn via page_allocator; graceful offline error if adapter absent
- build.zig: imports cartridge_shim from ../../../../ffi/zig/src/
- 12 unit tests covering all tools, error paths, and limit enforcement

Step 3: ReScript VSCode extension (panels/)
- Extension.res: activate/deactivate, resolves adapter dir from config or env
- VscodeApi.res: external bindings for window, workspace, output channel
- LanguageClient.res: external bindings for vscode-languageclient/node
- package.json: VSCode manifest + vscode-languageclient dep (platform exception)
- rescript.json: CommonJS output to lib/js/src/Extension.js
- All 12 domains accepted (routing inside adapter); trace.server configurable

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

cartridges/orchestrator-lsp-mcp/adapter/lib/lsp/handlers/completion.ex

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Merges completion item lists from multiple domain LSP servers.
+#
+# Strategy:
+#   1. Flatten all items from all domains into a single list.
+#   2. Prefix the item's "detail" field with "[<domain>]" so the user can
+#      see which domain contributed the suggestion.
+#   3. Deduplicate by "label" — first occurrence wins (domain order from
+#      Planner.route/2 acts as implicit priority).
+
+defmodule OrchestratorLspMcp.LSP.Handlers.Completion do
+  @moduledoc """
+  Merges completion item lists from multiple domain LSP servers.
+
+  Each domain returns a (possibly nil) list of LSP CompletionItem maps.
+  This module tags each item's `detail` field with the originating domain
+  and deduplicates by `label`, keeping the first occurrence.
+  """
+
+  @doc """
+  Merge a keyword list of `{domain, items}` pairs into a single
+  deduplicated completion list.
+
+  ## Examples
+
+      iex> Completion.merge([{"k8s", [%{"label" => "Pod"}]}, {"db", nil}])
+      [%{"label" => "Pod", "detail" => "[k8s] "}]
+  """
+  @spec merge([{String.t(), list(map()) | nil}]) :: list(map())
+  def merge(results) do
+    results
+    |> Enum.flat_map(fn {domain, items} ->
+      # Treat nil (domain unavailable or no results) as an empty list.
+      Enum.map(items || [], fn item ->
+        detail = Map.get(item, "detail", "")
+        Map.put(item, "detail", "[#{domain}] #{detail}")
+      end)
+    end)
+    |> Enum.uniq_by(& &1["label"])
+  end
+end

cartridges/orchestrator-lsp-mcp/adapter/lib/lsp/handlers/diagnostics.ex

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Merges diagnostic lists from multiple domain LSP servers for a single
+# document URI, to be published back to the editor via
+# textDocument/publishDiagnostics.
+#
+# Strategy:
+#   - Flatten all diagnostics from all domains.
+#   - Prefix each diagnostic's "source" field with "<domain>:" so the
+#     editor's Problems panel shows which server raised each issue.
+#   - Preserve the full LSP Diagnostic object otherwise (range, severity,
+#     message, code, etc.) so editors can render it correctly.
+
+defmodule OrchestratorLspMcp.LSP.Handlers.Diagnostics do
+  @moduledoc """
+  Merges diagnostic lists from multiple domain LSP servers.
+
+  Each domain returns a (possibly nil) list of LSP Diagnostic maps for a
+  given document URI. This module tags each diagnostic's `source` field
+  with the originating domain name and returns a single
+  publishDiagnostics payload map.
+  """
+
+  @doc """
+  Merge diagnostics from multiple domains for `uri`.
+
+  Returns a map ready to pass to GenLSP as a publishDiagnostics notification:
+
+      %{"uri" => uri, "diagnostics" => [...]}
+  """
+  @spec merge(String.t(), [{String.t(), list(map()) | nil}]) :: map()
+  def merge(uri, results) do
+    diagnostics =
+      Enum.flat_map(results, fn {domain, diags} ->
+        Enum.map(diags || [], fn d ->
+          # Prepend "<domain>:" to existing source (may be empty string).
+          existing_source = Map.get(d, "source", "")
+          Map.put(d, "source", "#{domain}:#{existing_source}")
+        end)
+      end)
+
+    %{"uri" => uri, "diagnostics" => diagnostics}
+  end
+end

cartridges/orchestrator-lsp-mcp/adapter/lib/lsp/handlers/hover.ex

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Merges hover responses from multiple domain LSP servers into a single
+# MarkupContent block presented to the editor.
+#
+# Strategy:
+#   - Filter out nil responses (domain had nothing to say).
+#   - Extract the "value" string from each domain's "contents" map.
+#   - Emit one markdown section per domain headed by "### <domain>".
+#   - Separate sections with a horizontal rule ("---").
+#   - Return nil when no domain produced a result (editor hides the hover).
+
+defmodule OrchestratorLspMcp.LSP.Handlers.Hover do
+  @moduledoc """
+  Merges hover responses from multiple domain LSP servers.
+
+  Each domain may return nil (no hover for this position) or a map
+  containing a `"contents"` key (MarkupContent or plain string).
+  Results are concatenated into a single markdown document with a
+  per-domain heading, or nil when all domains return nil.
+  """
+
+  @doc """
+  Merge a keyword list of `{domain, hover_result}` pairs.
+
+  Returns a merged LSP Hover map (`%{"contents" => %{"kind" => "markdown", ...}}`)
+  or `nil` if every domain returned nil.
+  """
+  @spec merge([{String.t(), map() | nil}]) :: map() | nil
+  def merge(results) do
+    contents =
+      results
+      |> Enum.reject(fn {_domain, r} -> is_nil(r) end)
+      |> Enum.map(fn {domain, r} ->
+        # Support both MarkupContent (%{"contents" => %{"value" => ...}})
+        # and plain string contents (%{"contents" => "..."}).
+        body =
+          get_in(r, ["contents", "value"]) ||
+            get_in(r, ["contents"]) ||
+            ""
+
+        "### #{domain}\n\n#{body}"
+      end)
+
+    case contents do
+      [] ->
+        nil
+
+      sections ->
+        %{
+          "contents" => %{
+            "kind" => "markdown",
+            "value" => Enum.join(sections, "\n\n---\n\n")
+          }
+        }
+    end
+  end
+end

cartridges/orchestrator-lsp-mcp/adapter/lib/lsp/server.ex

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# GenLSP server entry-point for the orchestrator cartridge.
+#
+# Responsibilities:
+#   - Negotiate LSP capabilities with the editor client (initialize handshake)
+#   - Delegate textDocument/completion and textDocument/hover requests to
+#     Executor.fan_out/3, which fans them out to the active domain servers in
+#     parallel and merges the results.
+#   - Broadcast open/change/close notifications to all active domain servers.
+#   - Relay publishDiagnostics push-notifications from domain servers back to
+#     the editor (wired via Executor, not handled directly here).
+#
+# State (lsp.assigns):
+#   :domains      – list of %{domain: string, port: integer} maps from Planner
+#   :session_id   – opaque reference used for VeriSimDB session tracking
+
+defmodule OrchestratorLspMcp.LSP.Server do
+  use GenLSP
+
+  alias OrchestratorLspMcp.Orchestrator.{Planner, Executor}
+  alias OrchestratorLspMcp.VeriSimDB.Client, as: DB
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Lifecycle
+  # ──────────────────────────────────────────────────────────────────────
+
+  @impl true
+  def init(lsp, _args) do
+    {:ok, assign(lsp, domains: [], session_id: nil)}
+  end
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Request handlers
+  # ──────────────────────────────────────────────────────────────────────
+
+  @impl true
+  def handle_request(%GenLSP.Requests.Initialize{} = req, lsp) do
+    root = get_in(req, [:params, :rootUri])
+    domains = Planner.active_domains(root)
+    session_id = make_ref()
+
+    # Persist session asynchronously — VeriSimDB unavailability must not
+    # block the initialize handshake.
+    Task.start(fn -> DB.record_session(session_id, domains, root || "") end)
+
+    caps = Planner.merged_capabilities(domains)
+
+    {:reply, %{capabilities: caps},
+     assign(lsp, domains: domains, session_id: session_id)}
+  end
+
+  @impl true
+  def handle_request(%GenLSP.Requests.TextDocumentCompletion{} = req, lsp) do
+    result = Executor.fan_out(:completion, req.params, lsp.assigns.domains)
+    {:reply, result, lsp}
+  end
+
+  @impl true
+  def handle_request(%GenLSP.Requests.TextDocumentHover{} = req, lsp) do
+    result = Executor.fan_out(:hover, req.params, lsp.assigns.domains)
+    {:reply, result, lsp}
+  end
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Notification handlers
+  # ──────────────────────────────────────────────────────────────────────
+
+  @impl true
+  def handle_notification(%GenLSP.Notifications.Initialized{}, lsp) do
+    # Nothing to do beyond acknowledging the handshake is complete.
+    {:noreply, lsp}
+  end
+
+  @impl true
+  def handle_notification(%GenLSP.Notifications.TextDocumentDidOpen{} = notif, lsp) do
+    Executor.broadcast_notification(:did_open, notif.params, lsp.assigns.domains)
+    {:noreply, lsp}
+  end
+
+  @impl true
+  def handle_notification(%GenLSP.Notifications.TextDocumentDidChange{} = notif, lsp) do
+    Executor.broadcast_notification(:did_change, notif.params, lsp.assigns.domains)
+    {:noreply, lsp}
+  end
+
+  @impl true
+  def handle_notification(%GenLSP.Notifications.TextDocumentDidClose{} = notif, lsp) do
+    Executor.broadcast_notification(:did_close, notif.params, lsp.assigns.domains)
+
+    # Close VeriSimDB session when the last document is closed (best-effort).
+    Task.start(fn -> DB.close_session(lsp.assigns.session_id) end)
+
+    {:noreply, lsp}
+  end
+
+  # Catch-all: ignore unknown notifications silently.
+  @impl true
+  def handle_notification(_, lsp), do: {:noreply, lsp}
+end

cartridges/orchestrator-lsp-mcp/adapter/lib/orchestrator/executor.ex

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Fans out LSP requests to the selected domain servers in parallel and
+# merges their responses via the appropriate Handlers module.
+#
+# fan_out/3         – parallel request + merge for :completion and :hover
+# broadcast_notification/3 – fire-and-forget notification relay to all domains
+#
+# Failure isolation:
+#   - Per-domain tasks that time out or crash are silently dropped (domain
+#     unavailability must never crash the orchestrator).
+#   - The @timeout is intentionally conservative (5 s) to avoid stacking
+#     slow domains into a cascade that blocks the editor.
+
+defmodule OrchestratorLspMcp.Orchestrator.Executor do
+  @moduledoc """
+  Fans out LSP requests to domain servers in parallel and merges results.
+
+  Uses `Task.async_stream/3` for parallel request dispatch with a hard
+  per-domain timeout. Timed-out or crashed tasks are silently dropped so
+  that a single offline domain never blocks completion/hover for the rest.
+  """
+
+  alias OrchestratorLspMcp.Orchestrator.{Planner, LSPClientPool}
+  alias OrchestratorLspMcp.LSP.Handlers.{Completion, Hover}
+
+  # Per-domain request timeout in milliseconds.
+  @timeout 5_000
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Public API
+  # ──────────────────────────────────────────────────────────────────────
+
+  @doc """
+  Fan out `method` (:completion | :hover) to the domains selected by
+  Planner.route/2 and merge the results.
+
+  Returns the merged LSP response (list for completion, map/nil for hover).
+  """
+  @spec fan_out(:completion | :hover, map(), [map()]) :: term()
+  def fan_out(:completion, params, domains) do
+    uri = get_in(params, ["textDocument", "uri"]) || ""
+    routed = Planner.route(uri, domains)
+    results = parallel_request(routed, :completion, params)
+    Completion.merge(results)
+  end
+
+  def fan_out(:hover, params, domains) do
+    uri = get_in(params, ["textDocument", "uri"]) || ""
+    routed = Planner.route(uri, domains)
+    results = parallel_request(routed, :hover, params)
+    Hover.merge(results)
+  end
+
+  @doc """
+  Broadcast a notification to all active domain servers.
+
+  Fire-and-forget: errors and timeouts per domain are silently swallowed.
+  Uses `Task.Supervisor.async_stream_nolink/4` to avoid linking the
+  broadcast tasks to the calling process.
+  """
+  @spec broadcast_notification(atom(), map(), [map()]) :: :ok
+  def broadcast_notification(method, params, domains) do
+    Task.Supervisor.async_stream_nolink(
+      OrchestratorLspMcp.ExecutionSupervisor,
+      domains,
+      fn d -> send_notification(d, method, params) end,
+      timeout: @timeout,
+      on_timeout: :kill_task
+    )
+    |> Stream.run()
+
+    :ok
+  end
+
+  # ──────────────────────────────────────────────────────────────────────
+  # Private helpers
+  # ──────────────────────────────────────────────────────────────────────
+
+  # Dispatch `method` to each domain in parallel; collect {domain, result} pairs.
+  # Tasks that exit (timeout or crash) produce no result entry.
+  defp parallel_request(domains, method, params) do
+    domains
+    |> Task.async_stream(
+      fn d -> {d.domain, send_request(d, method, params)} end,
+      timeout: @timeout,
+      on_timeout: :kill_task
+    )
+    |> Enum.flat_map(fn
+      {:ok, result} -> [result]
+      # Drop timed-out or crashed tasks without propagating the error.
+      {:exit, _reason} -> []
+    end)
+  end
+
+  # Send a synchronous LSP request to a single domain client process.
+  # Returns nil if the domain is not registered in the pool, or on any error.
+  defp send_request(domain_info, method, params) do
+    case LSPClientPool.get(domain_info.domain) do
+      nil ->
+        nil
+
+      pid ->
+        GenServer.call(pid, {:request, method, params}, @timeout)
+    end
+  rescue
+    # Catch exit/timeout from GenServer.call so callers always get a value.
+    _ -> nil
+  end
+
+  # Send a fire-and-forget cast to a single domain client process.
+  defp send_notification(domain_info, method, params) do
+    case LSPClientPool.get(domain_info.domain) do
+      nil -> :noop
+      pid -> GenServer.cast(pid, {:notification, method, params})
+    end
+  end
+end