feat(bridge): replace koffi FFI with a NAPI addon (bridge.node)

The bridge now builds as a NAPI addon that Node loads directly via
require() — no FFI library dependency.

- napi_shim.c (~150 lines): exposes newSession/call/callBinary/
  disposeSession with one marshalling pattern — JS strings copied into
  shim-owned buffers freed before return; string results are Go-owned
  reusable buffers V8 copies (napi_create_string_utf8); binary results
  copied via napi_create_buffer_copy. Nothing escapes the shim scope,
  everything synchronous on the JS thread.
- tsgoChecker: require(bridge.node) instead of koffi.load; BridgeClient
  passes plain JS strings and consumes Buffers directly (no
  koffi.struct/decode/toCStr).
- build-bridge.js: emits bridge.node for every platform, resolves node
  headers from the running Node (NAPI is ABI-stable), links
  -undefined dynamic_lookup on darwin and node.lib on win32
  (TNB_NODE_LIB; release workflow downloads it per arch).
- koffi removed from dependencies; check-lib-sync loader marker moved
  from koffi to bridge.node.
- tools/triage-napi-fuzz.mjs: 9 pathological payloads x 2 paths +
  60-call reusable-buffer stability — byte-identical round trips.

Verified: koffi-vs-NAPI side-by-side smoke byte-identical; sim-nav
37,409 units new=0; sim-xfile 71/71; sim-edit THROWS 0; f2hl/f2r6/
emptyparity/refs-exportspec/display-tokens/computed-literal PASS;
check:lib/enums/sourcefile-guard ok; volar suite 205/205.

Author: johnsoncodehk

.github/workflows/release.yml

@@ -77,8 +77,8 @@ jobs:
           - { target: linux-x64, runner: ubuntu-latest }
           - { target: linux-arm64, runner: ubuntu-24.04-arm }
           - { target: linux-arm, runner: ubuntu-latest, goos: linux, goarch: arm, goarm: "7", cc: arm-linux-gnueabihf-gcc, apt: gcc-arm-linux-gnueabihf }
-          - { target: win32-x64, runner: ubuntu-latest, goos: windows, goarch: amd64, cc: x86_64-w64-mingw32-gcc, apt: gcc-mingw-w64-x86-64 }
-          - { target: win32-arm64, runner: ubuntu-latest, goos: windows, goarch: arm64, cc: aarch64-w64-mingw32-gcc, llvm_mingw: "1" }
+          - { target: win32-x64, runner: ubuntu-latest, goos: windows, goarch: amd64, cc: x86_64-w64-mingw32-gcc, apt: gcc-mingw-w64-x86-64, node_lib: "https://nodejs.org/dist/v24.15.0/win-x64/node.lib" }
+          - { target: win32-arm64, runner: ubuntu-latest, goos: windows, goarch: arm64, cc: aarch64-w64-mingw32-gcc, llvm_mingw: "1", node_lib: "https://nodejs.org/dist/v24.15.0/win-arm64/node.lib" }
     runs-on: ${{ matrix.runner }}
     steps:
       - uses: actions/checkout@v4
@@ -109,6 +109,10 @@ jobs:
           curl -sSL https://github.com/mstorsjo/llvm-mingw/releases/download/20250417/llvm-mingw-20250417-ucrt-ubuntu-22.04-x86_64.tar.xz | sudo tar -xJ -C /opt
           echo "/opt/llvm-mingw-20250417-ucrt-ubuntu-22.04-x86_64/bin" >> "$GITHUB_PATH"
 
+      - name: Download node.lib (windows targets)
+        if: matrix.node_lib
+        run: curl -sSL "${{ matrix.node_lib }}" -o /tmp/node.lib
+
       - name: Build bridge (stripped)
         run: node tools/build-bridge.js
         env:
@@ -118,6 +122,7 @@ jobs:
           CC: ${{ matrix.cc }}
           CGO_CFLAGS: ${{ matrix.cgo_cflags }}
           CGO_LDFLAGS: ${{ matrix.cgo_ldflags }}
+          TNB_NODE_LIB: ${{ matrix.node_lib != null && '/tmp/node.lib' || '' }}
           CGO_ENABLED: 1
           TNB_STRIP: 1
 

package-lock.json

@@ -43,7 +43,5 @@
 		"build:ts": "node tools/patch-typescript.js && cd typescript && npm install && npm run build:compiler && npx hereby lkg",
 		"build:bridge": "node tools/patch-tsgo.js && node tools/build-bridge.js"
 	},
-	"dependencies": {
-		"koffi": "^2.16.0"
-	}
+	"dependencies": {}
 }

package.json

@@ -1,7 +1,7 @@
 // Package main is a Proof-of-Concept NAPI/FFI bridge for typescript-go.
 //
-// It builds as a C-shared library (`go build -buildmode=c-shared`) and exposes
-// a tiny C ABI that Node.js can load via an FFI library (koffi). The bridge
+// It builds as a NAPI addon (`go build -buildmode=c-shared` → bridge.node,
+// see napi_shim.c) that Node.js loads directly via require(). The bridge
 // reuses the exact same api.Session / project.Session machinery that the IPC
 // stdio server uses — every type/symbol/source-file query goes through
 // Session.HandleRequest, so there is zero handler duplication. The only thing
@@ -12,17 +12,17 @@
 //   - BridgeCallBinary  -> raw bytes (for getSourceFile etc.), single-copy into a Node Buffer
 //
 // Memory model: both paths write into reusable C buffers. Calls are fully
-// synchronous, so koffi copies the data out at the FFI boundary before the
-// next call reuses the buffer. Zero per-call malloc, zero leaks.
+// synchronous, so the NAPI shim copies the data out to V8 before the next call
+// reuses the buffer. Zero per-call malloc, zero leaks.
 package main
 
 /*
 #include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 
-// BridgeBinary is returned by value from BridgeCallBinary. Layout must match
-// the koffi struct declared on the JS side: { void* data; int64_t len; }.
+// BridgeBinary is returned by value from BridgeCallBinary. Layout matches
+// napi_shim.c's declaration: { void* data; int64_t len; }.
 struct BridgeBinary { void* data; long long len; };
 */
 import "C"

patches/typescript-go/overlay/bridge/bridge.go

@@ -0,0 +1,167 @@
+// napi_shim.c — NAPI entry for the TNB cgo bridge (replaces the koffi FFI).
+//
+// Node loads bridge.node directly via require(); no FFI library needed.
+//
+// Marshalling contract (deliberately tiny — see the design discussion):
+//   - Shapes: strings in, string-or-Buffer out, int64 session handle. Nothing
+//     else ever crosses the boundary (envelopes are JSON, parsed in JS).
+//   - Inputs: JS strings are copied into shim-owned buffers (C.GoString copies
+//     again on the Go side), freed before the shim returns.
+//   - String results: Go-owned reusable buffer (resultBuf in bridge.go),
+//     copied into V8 by napi_create_string_utf8. Nothing to free — Go keeps
+//     ownership and recycles it on the next call.
+//   - Binary results: Go-owned reusable buffer (binBuf), copied by
+//     napi_create_buffer_copy. Same ownership rule.
+//   - Everything synchronous on the JS thread. No async NAPI, no callbacks,
+//     no thread-safe functions.
+
+#include <node_api.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+// cgo-exported Go entry points (bridge.go).
+struct BridgeBinary { void* data; long long len; };
+extern char* BridgeNewSession(char* cwd);
+extern char* BridgeCall(int64_t session, char* method, char* paramsJson);
+extern struct BridgeBinary BridgeCallBinary(int64_t session, char* method, char* paramsJson);
+extern void BridgeDisposeSession(int64_t session);
+
+// Required string argument → fresh NUL-terminated buffer (caller frees).
+// Returns NULL with nothing set if conversion fails (napi raises then).
+static char* arg_string(napi_env env, napi_value v, bool* ok) {
+	*ok = false;
+	size_t len = 0;
+	if (napi_get_value_string_utf8(env, v, NULL, 0, &len) != napi_ok) return NULL;
+	char* buf = (char*)malloc(len + 1);
+	if (!buf) {
+		napi_throw_error(env, NULL, "tnb bridge: out of memory");
+		return NULL;
+	}
+	if (napi_get_value_string_utf8(env, v, buf, len + 1, NULL) != napi_ok) {
+		free(buf);
+		return NULL;
+	}
+	*ok = true;
+	return buf;
+}
+
+// Optional string argument: NULL for null/undefined.
+static char* arg_string_opt(napi_env env, napi_value v, bool* ok) {
+	napi_valuetype t = napi_undefined;
+	if (napi_typeof(env, v, &t) != napi_ok) { *ok = false; return NULL; }
+	if (t == napi_null || t == napi_undefined) { *ok = true; return NULL; }
+	return arg_string(env, v, ok);
+}
+
+// Session handle: accept Number or BigInt.
+static int64_t arg_int64(napi_env env, napi_value v) {
+	napi_valuetype t = napi_undefined;
+	napi_typeof(env, v, &t);
+	if (t == napi_bigint) {
+		int64_t out = 0;
+		bool lossless = false;
+		napi_get_value_bigint_int64(env, v, &out, &lossless);
+		return out;
+	}
+	double d = 0;
+	napi_get_value_double(env, v, &d);
+	return (int64_t)d;
+}
+
+static napi_value js_string(napi_env env, const char* s) {
+	napi_value out = NULL;
+	napi_create_string_utf8(env, s, NAPI_AUTO_LENGTH, &out);
+	return out;
+}
+
+// newSession(cwd: string): string (JSON envelope with the session handle)
+static napi_value fn_new_session(napi_env env, napi_callback_info info) {
+	napi_value argv[1];
+	size_t argc = 1;
+	napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
+	bool ok;
+	char* cwd = arg_string(env, argv[0], &ok);
+	if (!ok) return NULL;
+	char* out = BridgeNewSession(cwd);
+	free(cwd);
+	return js_string(env, out);
+}
+
+// Shared argument extraction for call / callBinary.
+// Returns false with any allocated memory already freed.
+static bool call_args(napi_env env, napi_callback_info info, int64_t* session, char** method, char** params) {
+	napi_value argv[3];
+	size_t argc = 3;
+	*method = NULL;
+	*params = NULL;
+	napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
+	*session = arg_int64(env, argv[0]);
+	bool ok;
+	*method = arg_string(env, argv[1], &ok);
+	if (!ok) return false;
+	*params = arg_string_opt(env, argv[2], &ok);
+	if (!ok) {
+		free(*method);
+		*method = NULL;
+		return false;
+	}
+	return true;
+}
+
+// call(session, method, paramsJson | null): string (JSON envelope)
+static napi_value fn_call(napi_env env, napi_callback_info info) {
+	int64_t session;
+	char* method;
+	char* params;
+	if (!call_args(env, info, &session, &method, &params)) return NULL;
+	char* out = BridgeCall(session, method, params);
+	free(method);
+	free(params);
+	return js_string(env, out);
+}
+
+// callBinary(session, method, paramsJson | null): Buffer | null
+static napi_value fn_call_binary(napi_env env, napi_callback_info info) {
+	int64_t session;
+	char* method;
+	char* params;
+	if (!call_args(env, info, &session, &method, &params)) return NULL;
+	struct BridgeBinary res = BridgeCallBinary(session, method, params);
+	free(method);
+	free(params);
+	if (res.len <= 0 || res.data == NULL) {
+		napi_value nul;
+		napi_get_null(env, &nul);
+		return nul;
+	}
+	napi_value buf = NULL;
+	void* dst = NULL;
+	// V8 copies the bytes; Go keeps the source (reusable binBuf).
+	napi_create_buffer_copy(env, (size_t)res.len, res.data, &dst, &buf);
+	return buf;
+}
+
+// disposeSession(session): void
+static napi_value fn_dispose_session(napi_env env, napi_callback_info info) {
+	napi_value argv[1];
+	size_t argc = 1;
+	napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
+	BridgeDisposeSession(arg_int64(env, argv[0]));
+	napi_value undef;
+	napi_get_undefined(env, &undef);
+	return undef;
+}
+
+static bool set_fn(napi_env env, napi_value exports, const char* name, napi_callback cb) {
+	napi_value fn = NULL;
+	if (napi_create_function(env, name, NAPI_AUTO_LENGTH, cb, NULL, &fn) != napi_ok) return false;
+	return napi_set_named_property(env, exports, name, fn) == napi_ok;
+}
+
+napi_value napi_register_module_v1(napi_env env, napi_value exports) {
+	set_fn(env, exports, "newSession", fn_new_session);
+	set_fn(env, exports, "call", fn_call);
+	set_fn(env, exports, "callBinary", fn_call_binary);
+	set_fn(env, exports, "disposeSession", fn_dispose_session);
+	return exports;
+}