@obinexusltd/curl-polycall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OBINexus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,122 @@
+ifneq ($(OS),Windows_NT)
+ifeq ($(origin CC),default)
+CC := cc
+endif
+endif
+CFLAGS ?= -O2 -Wall -Wextra
+PIC_FLAGS ?= -fPIC
+
+SRC := src/polycall_ffi.c
+OBJ_DIR := build/obj
+BIN_DIR := build/bin
+OBJ := $(OBJ_DIR)/polycall_ffi.o
+
+DESTDIR ?=
+PREFIX ?= /usr/local
+SYSCONFDIR ?= /etc
+BINDIR ?= $(PREFIX)/bin
+LIBEXECDIR ?= $(PREFIX)/lib/curl-polycall
+DOCDIR ?= $(PREFIX)/share/doc/curl-polycall
+EXAMPLESDIR ?= $(PREFIX)/share/curl-polycall/examples
+
+ifeq ($(OS),Windows_NT)
+PIC_FLAGS :=
+PYTHON ?= python
+LIB := $(BIN_DIR)/polycall_ffi.dll
+TMP_LIB := $(BIN_DIR)/polycall_ffi.tmp.dll
+SHARED_FLAGS := -shared
+else
+PYTHON ?= python3
+UNAME_S := $(shell uname -s 2>/dev/null || echo Unknown)
+ifeq ($(UNAME_S),Darwin)
+LIB := $(BIN_DIR)/libpolycall_ffi.dylib
+SHARED_FLAGS := -dynamiclib
+else
+LIB := $(BIN_DIR)/libpolycall_ffi.so
+SHARED_FLAGS := -shared
+endif
+endif
+
+.PHONY: all clean dirs install uninstall run windows-build FORCE
+
+ifeq ($(OS),Windows_NT)
+all: windows-build
+else
+all: dirs $(LIB)
+endif
+
+FORCE:
+
+ifeq ($(OS),Windows_NT)
+dirs:
+	@if not exist "build" mkdir "build"
+	@if not exist "build\bin" mkdir "build\bin"
+	@if not exist "build\obj" mkdir "build\obj"
+else
+dirs:
+	mkdir -p $(BIN_DIR) $(OBJ_DIR)
+endif
+
+$(OBJ): FORCE $(SRC) src/polycall_ffi.h | dirs
+	$(CC) $(CFLAGS) $(PIC_FLAGS) -c $(SRC) -o $(OBJ)
+
+ifeq ($(OS),Windows_NT)
+windows-build: dirs
+	powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-windows.ps1
+else
+$(LIB): $(OBJ) | dirs
+	$(CC) $(SHARED_FLAGS) $(OBJ) -o $(LIB)
+endif
+
+run: all
+	$(PYTHON) server.py
+
+ifeq ($(OS),Windows_NT)
+install:
+	@echo "make install is only supported on Unix-like systems"
+	@exit 1
+
+uninstall:
+	@echo "make uninstall is only supported on Unix-like systems"
+	@exit 1
+else
+install: all
+	install -d "$(DESTDIR)$(BINDIR)"
+	install -d "$(DESTDIR)$(LIBEXECDIR)"
+	install -d "$(DESTDIR)$(LIBEXECDIR)/build/bin"
+	install -d "$(DESTDIR)$(SYSCONFDIR)/curl-polycall"
+	install -d "$(DESTDIR)$(DOCDIR)"
+	install -d "$(DESTDIR)$(EXAMPLESDIR)"
+	install -m 0644 ffi.py server.py "$(DESTDIR)$(LIBEXECDIR)/"
+	install -m 0644 "$(LIB)" "$(DESTDIR)$(LIBEXECDIR)/build/bin/"
+	install -m 0644 config/curl-polycall.env "$(DESTDIR)$(SYSCONFDIR)/curl-polycall/curl-polycall.env"
+	install -m 0644 README.md LICENSE "$(DESTDIR)$(DOCDIR)/"
+	install -m 0644 docs/FAULT_TOLERANT_FFI_PROOF.md "$(DESTDIR)$(DOCDIR)/"
+	install -m 0755 examples/curl.sh "$(DESTDIR)$(EXAMPLESDIR)/curl.sh"
+	sed -e 's|@LIBEXECDIR@|$(LIBEXECDIR)|g' \
+		-e 's|@SYSCONFDIR@|$(SYSCONFDIR)|g' \
+		scripts/curl-polycall-server.in > "$(DESTDIR)$(BINDIR)/curl-polycall-server"
+	chmod 0755 "$(DESTDIR)$(BINDIR)/curl-polycall-server"
+	sed -e 's|@BINDIR@|$(BINDIR)|g' \
+		-e 's|@EXAMPLESDIR@|$(EXAMPLESDIR)|g' \
+		scripts/curl-polycall.in > "$(DESTDIR)$(BINDIR)/curl-polycall"
+	chmod 0755 "$(DESTDIR)$(BINDIR)/curl-polycall"
+
+uninstall:
+	rm -f "$(DESTDIR)$(BINDIR)/curl-polycall" "$(DESTDIR)$(BINDIR)/curl-polycall-server"
+	rm -rf "$(DESTDIR)$(LIBEXECDIR)"
+	rm -rf "$(DESTDIR)$(DOCDIR)"
+	rm -rf "$(DESTDIR)$(EXAMPLESDIR)"
+	rm -f "$(DESTDIR)$(SYSCONFDIR)/curl-polycall/curl-polycall.env"
+	rmdir "$(DESTDIR)$(SYSCONFDIR)/curl-polycall" 2>/dev/null || true
+endif
+
+ifeq ($(OS),Windows_NT)
+clean:
+	@if exist "build\bin\polycall_ffi.dll" del /q "build\bin\polycall_ffi.dll"
+	@if exist "build\bin\polycall_ffi.tmp.dll" del /q "build\bin\polycall_ffi.tmp.dll"
+	@if exist "build\obj\polycall_ffi.o" del /q "build\obj\polycall_ffi.o"
+else
+clean:
+	rm -rf $(BIN_DIR)/* $(OBJ_DIR)/*
+endif

package/README.md

@@ -0,0 +1,206 @@
+# curl-polycall
+
+Minimal direct FFI demonstration for libpolycall-style command interpolation through `curl` or `wget`.
+
+The point of this example is narrow:
+
+- expose a tiny native C ABI;
+- load it from Python 3 with `import ffi`;
+- serve HTTP endpoints that call the native ABI directly;
+- keep NSIGII as an external attachable artifact, not C code inside libpolycall;
+- keep `micro attach` and `micro detach` as runtime dependency registration only.
+
+## Layout
+
+```text
+curl-polycall/
+|-- build/
+|   |-- bin/
+|   `-- obj/
+|-- config/
+|   `-- curl-polycall.env
+|-- debian/
+|   |-- control
+|   |-- rules
+|   `-- source/
+|-- docs/
+|   |-- FAULT_TOLERANT_FFI_PROOF.md
+|   `-- UNIX_PACKAGING.md
+|-- examples/
+|   |-- curl.ps1
+|   `-- curl.sh
+|-- scripts/
+|   `-- build-windows.ps1
+|-- src/
+|   |-- polycall_ffi.c
+|   `-- polycall_ffi.h
+|-- ffi.py
+|-- server.py
+|-- Makefile
+|-- package.json
+`-- README.md
+```
+
+## npm package metadata
+
+The project root includes `package.json` for the npm package
+`@obinexusltd/curl-polycall`. The package metadata lists every source folder in
+`directories` and keeps generated native build outputs out of the source package
+while preserving `build/bin` and `build/obj` with `.gitkeep` placeholders.
+
+The package also exposes two CLI entry points via npm:
+
+- `curl-polycall` → `scripts/curl-polycall.in`
+- `curl-polycall-server` → `scripts/curl-polycall-server.in`
+
+Install globally or run through `npx`:
+
+```sh
+npm install -g @obinexusltd/curl-polycall
+curl-polycall server
+curl-polycall health
+curl-polycall command ping
+```
+
+Or run directly with `npx`:
+
+```sh
+npx @obinexusltd/curl-polycall server
+```
+
+Useful npm scripts:
+
+```sh
+npm run build
+npm run build:deb
+npm run build:windows
+npm start
+npm run demo
+npm run demo:windows
+npm run test:ffi
+```
+
+## Native ABI
+
+```c
+int polycall_verify_command(const char *command, char *out_buffer, int out_buffer_len);
+int polycall_runtime_micro_attach(const char *dependency_path, char *out_buffer, int out_buffer_len);
+int polycall_runtime_micro_detach(const char *dependency_path, char *out_buffer, int out_buffer_len);
+```
+
+Platform outputs:
+
+- Windows: `build/bin/polycall_ffi.dll`
+- Linux: `build/bin/libpolycall_ffi.so`
+- macOS: `build/bin/libpolycall_ffi.dylib`
+- Objects: `build/obj`
+
+## Build
+
+Linux/macOS:
+
+```sh
+make
+python3 server.py
+```
+
+Windows PowerShell:
+
+```powershell
+.\scripts\build-windows.ps1
+python server.py
+```
+
+If Windows reports `cannot open file 'build\bin\polycall_ffi.dll'` or
+`Permission denied`, stop the running server with `Ctrl+C` before rebuilding.
+Python keeps the DLL loaded while `server.py` is running.
+
+## Unix and apt install
+
+For generic Unix installs:
+
+```sh
+make
+sudo make install PREFIX=/usr SYSCONFDIR=/etc
+```
+
+For Debian/Ubuntu local apt installs:
+
+```sh
+sudo apt update
+sudo apt install build-essential debhelper devscripts
+chmod +x debian/rules scripts/build-deb.sh
+sh scripts/build-deb.sh
+sudo apt install ../curl-polycall_0.1.0_$(dpkg --print-architecture).deb
+```
+
+Then run:
+
+```sh
+curl-polycall server
+curl-polycall health
+curl-polycall command ping
+```
+
+Plain `sudo apt install curl-polycall` works only after the `.deb` is published
+to an apt repository configured on the machine. See
+[docs/UNIX_PACKAGING.md](docs/UNIX_PACKAGING.md).
+
+## Direct Python FFI
+
+```python
+import ffi
+
+runtime = ffi.load()
+runtime.command("ping")
+runtime.attach("build/bin/example.nsigii")
+runtime.detach("build/bin/example.nsigii")
+```
+
+## Curl endpoints
+
+Start the server first:
+
+```sh
+python server.py
+```
+
+Then call individual endpoints:
+
+```sh
+curl "http://127.0.0.1:8084/"
+curl "http://127.0.0.1:8084/command?cmd=ping"
+curl "http://127.0.0.1:8084/command?cmd=health"
+curl "http://127.0.0.1:8084/command?cmd=unknown"
+curl "http://127.0.0.1:8084/micro/attach?path=build/bin/example.nsigii"
+curl "http://127.0.0.1:8084/micro/detach?path=build/bin/example.nsigii"
+```
+
+Or run the example script:
+
+```sh
+bash examples/curl.sh
+```
+
+From PowerShell:
+
+```powershell
+.\examples\curl.ps1
+```
+
+Both example scripts wait briefly for `http://127.0.0.1:8084/` before sending
+the endpoint requests, so they can be launched while `server.py` is still
+starting.
+
+Do not run `curl.exe examples/curl.sh`; that asks curl to fetch a URL named
+`examples/curl.sh`. Use `bash examples/curl.sh` or the PowerShell script above.
+
+Each response is trinary JSON:
+
+```json
+{"status":"YES","message":"..."}
+{"status":"NO","message":"..."}
+{"status":"MAYBE","message":"..."}
+```
+
+Known commands return `YES`, invalid input returns `NO`, and unknown but syntactically valid commands return `MAYBE`.

package/build/bin/.gitkeep

@@ -0,0 +1 @@
+

package/build/obj/.gitkeep

@@ -0,0 +1 @@
+

package/config/curl-polycall.env

@@ -0,0 +1,7 @@
+# curl-polycall Unix runtime config
+#
+# This file is installed to /etc/curl-polycall/curl-polycall.env by the
+# Debian package and the POSIX Makefile install target.
+
+CURL_POLYCALL_HOST=127.0.0.1
+CURL_POLYCALL_PORT=8084

package/debian/changelog

@@ -0,0 +1,6 @@
+curl-polycall (0.1.0) unstable; urgency=medium
+
+  * Initial Debian package for the curl-polycall direct FFI demo.
+  * Install POSIX commands, FHS config, docs, examples, and native FFI library.
+
+ -- OBINexus LTD <support@obinexus.com>  Wed, 24 Jun 2026 21:30:00 +0000

package/debian/control

@@ -0,0 +1,27 @@
+Source: curl-polycall
+Section: net
+Priority: optional
+Maintainer: OBINexus LTD <support@obinexus.com>
+Build-Depends:
+ debhelper-compat (= 13),
+ gcc,
+ make,
+ python3
+Standards-Version: 4.6.2
+Rules-Requires-Root: no
+Homepage: https://github.com/obinexusltd/curl-polycall
+
+Package: curl-polycall
+Architecture: any
+Depends:
+ ${misc:Depends},
+ ${shlibs:Depends},
+ curl,
+ python3
+Description: Direct FFI curl endpoint demonstration for libpolycall
+ curl-polycall is a minimal verification-first Foreign Function Interface
+ demonstration. It exposes a native C ABI, loads it from Python with ctypes,
+ and serves curl/wget-friendly HTTP endpoints that return YES, NO, or MAYBE.
+ .
+ NSIGII artifacts remain external runtime dependencies; they are not embedded
+ into the native libpolycall demonstration.

package/debian/copyright

@@ -0,0 +1,26 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: curl-polycall
+Source: https://github.com/obinexusltd/curl-polycall
+
+Files: *
+Copyright: 2026 OBINexus
+License: MIT
+
+License: MIT
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.

package/debian/docs

@@ -0,0 +1,2 @@
+README.md
+docs/FAULT_TOLERANT_FFI_PROOF.md

package/debian/rules

@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+
+%:
+	dh $@
+
+override_dh_auto_build:
+	$(MAKE)
+
+override_dh_auto_install:
+	$(MAKE) install DESTDIR=$(CURDIR)/debian/curl-polycall PREFIX=/usr SYSCONFDIR=/etc
+
+override_dh_auto_clean:
+	$(MAKE) clean

package/debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

package/docs/FAULT_TOLERANT_FFI_PROOF.md

@@ -0,0 +1,70 @@
+# Fault-Tolerant Direct FFI Proof
+
+## Scope
+
+`curl-polycall` proves only the direct Foreign Function Interface boundary.
+
+It does not implement NSIGII as `nsigii.h` or `nsigii.c` inside libpolycall. It does not implement a DOP adapter. It does not copy microvm example code. NSIGII remains an external proof, artifact, or dependency that can be attached, detached, inspected, or loaded later by a runtime.
+
+## Direct FFI Call Chain
+
+The call chain is:
+
+```text
+curl/wget
+-> Python 3 http.server endpoint
+-> import ffi
+-> ctypes.CDLL(...)
+-> native C ABI function
+-> bounded JSON response buffer
+```
+
+The Python host performs a real foreign function call into the native shared library. The HTTP server is only a transport surface for command-line interoperability.
+
+## Native ABI Boundary
+
+The exported ABI is exactly:
+
+```c
+int polycall_verify_command(const char *command, char *out_buffer, int out_buffer_len);
+int polycall_runtime_micro_attach(const char *dependency_path, char *out_buffer, int out_buffer_len);
+int polycall_runtime_micro_detach(const char *dependency_path, char *out_buffer, int out_buffer_len);
+```
+
+Each function accepts caller-owned input plus a bounded output buffer. The C implementation writes responses with `snprintf`, checks truncation, and returns an error code if the buffer is invalid or too small.
+
+## Why NSIGII Is Not Embedded
+
+NSIGII is treated as an external artifact because libpolycall's responsibility here is native ABI interoperability, not NSIGII protocol logic. Embedding NSIGII directly as C headers or C source would collapse two separate concerns:
+
+- libpolycall: command interpolation, ABI boundary, language interop, runtime dependency attachment;
+- NSIGII: external proof/artifact/dependency semantics.
+
+Keeping NSIGII outside the native demo preserves the ability to attach, detach, inspect, or replace artifacts without rebuilding libpolycall.
+
+## Attach/Detach Is Separate From Execution
+
+`polycall_runtime_micro_attach` and `polycall_runtime_micro_detach` register dependency paths only. They do not load, invoke, fork, evaluate, or execute the dependency.
+
+This preserves a linkable-then-executable model: attachment establishes that a runtime dependency may be known to the runtime; execution remains a later, explicit phase outside this minimal proof.
+
+## Trinary Verification Model
+
+The response model is trinary:
+
+- `YES`: the command or dependency operation is accepted.
+- `NO`: the input is invalid, empty, or unsafe for registration.
+- `MAYBE`: the command is syntactically valid but not registered.
+
+This maps to verification-first command processing. The server never executes command strings. It asks the native ABI to verify the command, then returns the verification result.
+
+## Distributed Command-Line Interoperability
+
+`curl` and `wget` provide distributed command-line entry points:
+
+```sh
+curl "http://127.0.0.1:8084/command?cmd=ping"
+wget -qO- "http://127.0.0.1:8084/command?cmd=health"
+```
+
+The HTTP layer can be reached by ordinary command-line tools, while the actual decision boundary remains the native FFI call. That gives the demo a minimal decentralized shape: remote text request in, verification-first native ABI decision out.

package/docs/UNIX_PACKAGING.md

@@ -0,0 +1,98 @@
+# Unix Packaging And Apt Install
+
+## What apt can and cannot do
+
+`sudo apt install curl-polycall` only works after `curl-polycall` has been
+published into an apt repository that the machine knows about.
+
+For local development, build a `.deb` first and install it with:
+
+```sh
+sudo apt install ./curl-polycall_0.1.0_$(dpkg --print-architecture).deb
+```
+
+## Standard Unix Layout
+
+The package follows the Filesystem Hierarchy Standard:
+
+```text
+/usr/bin/curl-polycall
+/usr/bin/curl-polycall-server
+/usr/lib/curl-polycall/
+/usr/lib/curl-polycall/build/bin/libpolycall_ffi.so
+/etc/curl-polycall/curl-polycall.env
+/usr/share/doc/curl-polycall/
+/usr/share/curl-polycall/examples/
+```
+
+Runtime config is read from `/etc/curl-polycall/curl-polycall.env`:
+
+```sh
+CURL_POLYCALL_HOST=127.0.0.1
+CURL_POLYCALL_PORT=8084
+```
+
+## Debian/Ubuntu Local Package
+
+Install build tools:
+
+```sh
+sudo apt update
+sudo apt install build-essential debhelper devscripts
+```
+
+Build the Debian package:
+
+```sh
+chmod +x debian/rules scripts/build-deb.sh
+sh scripts/build-deb.sh
+```
+
+Install the local package:
+
+```sh
+sudo apt install ../curl-polycall_0.1.0_$(dpkg --print-architecture).deb
+```
+
+Use the installed commands:
+
+```sh
+curl-polycall server
+curl-polycall health
+curl-polycall command ping
+curl-polycall command unknown
+curl-polycall attach build/bin/example.nsigii
+curl-polycall detach build/bin/example.nsigii
+```
+
+## Generic Unix Install
+
+For Unix-like systems without apt:
+
+```sh
+make
+sudo make install PREFIX=/usr SYSCONFDIR=/etc
+```
+
+Remove:
+
+```sh
+sudo make uninstall PREFIX=/usr SYSCONFDIR=/etc
+```
+
+## Local Apt Repository
+
+After building the `.deb`, create a tiny local apt repository:
+
+```sh
+mkdir -p ~/apt-repo
+cp ../curl-polycall_0.1.0_$(dpkg --print-architecture).deb ~/apt-repo/
+cd ~/apt-repo
+dpkg-scanpackages . /dev/null | gzip -9c > Packages.gz
+echo "deb [trusted=yes] file:$HOME/apt-repo ./" | sudo tee /etc/apt/sources.list.d/curl-polycall-local.list
+sudo apt update
+sudo apt install curl-polycall
+```
+
+That is the step that makes plain `sudo apt install curl-polycall` work on a
+machine.

package/examples/curl.ps1

@@ -0,0 +1,33 @@
+#!/usr/bin/env pwsh
+$ErrorActionPreference = "Stop"
+
+$base = "http://127.0.0.1:8084"
+
+Write-Host "Waiting for curl-polycall at $base ..."
+$ready = $false
+for ($i = 0; $i -lt 30; $i++) {
+    curl.exe --silent --fail "$base/" > $null 2>$null
+    if ($LASTEXITCODE -eq 0) {
+        $ready = $true
+        break
+    }
+    Start-Sleep -Milliseconds 500
+}
+
+if (-not $ready) {
+    throw "curl-polycall is not reachable at $base. Start it with: python .\server.py"
+}
+
+$paths = @(
+    "/",
+    "/command?cmd=ping",
+    "/command?cmd=health",
+    "/command?cmd=unknown",
+    "/micro/attach?path=build/bin/example.nsigii",
+    "/micro/detach?path=build/bin/example.nsigii"
+)
+
+foreach ($path in $paths) {
+    curl.exe --silent --show-error "$base$path"
+    Write-Host ""
+}

package/examples/curl.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env sh
+set -eu
+base="http://127.0.0.1:8084"
+
+printf 'Waiting for curl-polycall at %s ...\n' "$base"
+ready=0
+i=0
+while [ "$i" -lt 30 ]; do
+    if curl --silent --fail --output /dev/null "$base/"; then
+        ready=1
+        break
+    fi
+    i=$((i + 1))
+    sleep 0.5
+done
+
+if [ "$ready" -ne 1 ]; then
+    printf 'curl-polycall is not reachable at %s. Start it with: python server.py\n' "$base" >&2
+    exit 1
+fi
+
+curl --silent --show-error "$base/"
+printf '\n'
+curl --silent --show-error "$base/command?cmd=ping"
+printf '\n'
+curl --silent --show-error "$base/command?cmd=health"
+printf '\n'
+curl --silent --show-error "$base/command?cmd=unknown"
+printf '\n'
+curl --silent --show-error "$base/micro/attach?path=build/bin/example.nsigii"
+printf '\n'
+curl --silent --show-error "$base/micro/detach?path=build/bin/example.nsigii"
+printf '\n'

package/ffi.py

@@ -0,0 +1,75 @@
+"""Direct FFI loader for curl-polycall.
+
+This module intentionally gives the Python side an `import ffi` surface.
+It uses ctypes from the Python standard library so no extra dependency is needed.
+"""
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+
+
+def _default_library_name() -> str:
+    system = platform.system().lower()
+    if system == "windows":
+        return "polycall_ffi.dll"
+    if system == "darwin":
+        return "libpolycall_ffi.dylib"
+    return "libpolycall_ffi.so"
+
+
+def _default_library_path() -> Path:
+    return ROOT / "build" / "bin" / _default_library_name()
+
+
+class PolycallFFI:
+    def __init__(self, library_path: str | os.PathLike[str] | None = None) -> None:
+        self.library_path = Path(library_path) if library_path else _default_library_path()
+        if not self.library_path.exists():
+            raise FileNotFoundError(
+                f"FFI library not found: {self.library_path}. Build it first."
+            )
+        try:
+            self.lib = ctypes.CDLL(str(self.library_path))
+        except OSError as exc:
+            raise OSError(
+                f"Unable to load FFI library {self.library_path}: {exc}. "
+                "Rebuild it with a compiler target that matches this Python process."
+            ) from exc
+        self._bind()
+
+    def _bind(self) -> None:
+        for name in (
+            "polycall_verify_command",
+            "polycall_runtime_micro_attach",
+            "polycall_runtime_micro_detach",
+        ):
+            fn = getattr(self.lib, name)
+            fn.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
+            fn.restype = ctypes.c_int
+
+    def _call(self, fn_name: str, value: str) -> str:
+        output = ctypes.create_string_buffer(1024)
+        fn = getattr(self.lib, fn_name)
+        code = fn(value.encode("utf-8"), output, len(output))
+        text = output.value.decode("utf-8", errors="replace")
+        if code != 0:
+            raise RuntimeError(f"{fn_name} failed with code {code}: {text}")
+        return text
+
+    def command(self, command: str) -> str:
+        return self._call("polycall_verify_command", command)
+
+    def attach(self, dependency_path: str) -> str:
+        return self._call("polycall_runtime_micro_attach", dependency_path)
+
+    def detach(self, dependency_path: str) -> str:
+        return self._call("polycall_runtime_micro_detach", dependency_path)
+
+
+def load(library_path: str | os.PathLike[str] | None = None) -> PolycallFFI:
+    return PolycallFFI(library_path)

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@obinexusltd/curl-polycall",
+  "version": "0.1.0",
+  "description": "Minimal curl-to-Python-to-native direct FFI demonstration for libpolycall.",
+  "license": "MIT",
+  "homepage": "https://github.com/obinexus/curl-polycall#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obinexusltd/curl-polycall.git"
+  },
+  "bugs": {
+    "url": "https://github.com/obinexusltd/curl-polycall/issues"
+  },
+  "keywords": [
+    "ffi",
+    "ctypes",
+    "curl",
+    "polycall",
+    "libpolycall",
+    "native-abi"
+  ],
+  "type": "commonjs",
+  "files": [
+    "build/bin/.gitkeep",
+    "build/obj/.gitkeep",
+    "config/",
+    "debian/",
+    "docs/",
+    "examples/",
+    "scripts/",
+    "src/",
+    "ffi.py",
+    "server.py",
+    "Makefile",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "curl-polycall": "scripts/curl-polycall.in",
+    "curl-polycall-server": "scripts/curl-polycall-server.in"
+  },
+  "directories": {
+    "build": "build",
+    "buildBin": "build/bin",
+    "buildObj": "build/obj",
+    "config": "config",
+    "debian": "debian",
+    "doc": "docs",
+    "example": "examples",
+    "lib": "src",
+    "scripts": "scripts",
+    "src": "src"
+  },
+  "scripts": {
+    "build": "make",
+    "build:deb": "sh scripts/build-deb.sh",
+    "build:windows": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-windows.ps1",
+    "clean": "make clean",
+    "demo": "sh examples/curl.sh",
+    "demo:windows": "powershell -NoProfile -ExecutionPolicy Bypass -File examples/curl.ps1",
+    "start": "python server.py",
+    "start:python3": "python3 server.py",
+    "test:ffi": "python -c \"import ffi; runtime = ffi.load(); print(runtime.command('ping'))\""
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-deb.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+set -eu
+
+if ! command -v dpkg-buildpackage >/dev/null 2>&1; then
+    cat >&2 <<'MSG'
+dpkg-buildpackage was not found.
+
+Install the Debian packaging toolchain first:
+  sudo apt update
+  sudo apt install build-essential debhelper devscripts
+MSG
+    exit 1
+fi
+
+dpkg-buildpackage -us -uc -b
+
+cat <<'MSG'
+
+Debian package build complete.
+
+Install locally with:
+  sudo apt install ../curl-polycall_0.1.0_$(dpkg --print-architecture).deb
+
+After install:
+  curl-polycall server
+  curl-polycall health
+  curl-polycall command ping
+MSG

package/scripts/build-windows.ps1

@@ -0,0 +1,69 @@
+$ErrorActionPreference = "Stop"
+
+New-Item -ItemType Directory -Force -Path build/bin | Out-Null
+New-Item -ItemType Directory -Force -Path build/obj | Out-Null
+Remove-Item -Force -ErrorAction SilentlyContinue `
+    build/bin/polycall_ffi.tmp.dll, `
+    build/obj/polycall_ffi.tmp.o
+
+function Test-LastExitCode {
+    param([string]$Label)
+    if ($LASTEXITCODE -ne 0) {
+        throw "$Label failed with exit code $LASTEXITCODE"
+    }
+}
+
+function Move-BuiltDll {
+    try {
+        if (Test-Path build/bin/polycall_ffi.dll) {
+            Remove-Item -Force build/bin/polycall_ffi.dll
+        }
+        Move-Item -Force build/bin/polycall_ffi.tmp.dll build/bin/polycall_ffi.dll
+    } catch {
+        Remove-Item -Force -ErrorAction SilentlyContinue build/bin/polycall_ffi.tmp.dll
+        throw "Cannot replace build/bin/polycall_ffi.dll. Stop the running Python server first because Windows keeps loaded DLLs locked. Original error: $($_.Exception.Message)"
+    }
+}
+
+$clCommand = "cl /nologo /W4 /O2 /LD /Fe:build\bin\polycall_ffi.tmp.dll /Fo:build\obj\polycall_ffi.obj src\polycall_ffi.c /link /IMPLIB:build\obj\polycall_ffi.lib /PDB:build\obj\polycall_ffi.pdb"
+$vcvarsCandidates = @(
+    "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat",
+    "C:\Program Files\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat",
+    "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
+)
+
+foreach ($vcvars in $vcvarsCandidates) {
+    if (Test-Path $vcvars) {
+        $cmd = "`"$vcvars`" >nul && $clCommand"
+        cmd.exe /d /s /c $cmd
+        Test-LastExitCode "MSVC x64 build"
+        Move-BuiltDll
+        Write-Host "Built build/bin/polycall_ffi.dll with MSVC x64"
+        exit 0
+    }
+}
+
+if ($env:INCLUDE -and $env:LIB -and (Get-Command cl.exe -ErrorAction SilentlyContinue)) {
+    cl /nologo /W4 /O2 /LD /Fe:build\bin\polycall_ffi.tmp.dll /Fo:build\obj\polycall_ffi.obj src\polycall_ffi.c /link /IMPLIB:build\obj\polycall_ffi.lib /PDB:build\obj\polycall_ffi.pdb
+    Test-LastExitCode "MSVC build"
+    Move-BuiltDll
+    Write-Host "Built build/bin/polycall_ffi.dll with MSVC"
+    exit 0
+}
+
+if (Get-Command gcc.exe -ErrorAction SilentlyContinue) {
+    $target = (gcc -dumpmachine).Trim()
+    if ($target -match "mingw32") {
+        Write-Warning "GCC target '$target' is commonly 32-bit; the DLL may not load into 64-bit Python."
+    }
+    gcc -O2 -Wall -Wextra -c src/polycall_ffi.c -o build/obj/polycall_ffi.tmp.o
+    Test-LastExitCode "GCC compile"
+    gcc -shared build/obj/polycall_ffi.tmp.o -o build/bin/polycall_ffi.tmp.dll
+    Test-LastExitCode "GCC link"
+    Move-Item -Force build/obj/polycall_ffi.tmp.o build/obj/polycall_ffi.o
+    Move-BuiltDll
+    Write-Host "Built build/bin/polycall_ffi.dll with GCC"
+    exit 0
+}
+
+throw "No Windows C compiler found. Install Visual Studio Build Tools or MinGW GCC."

package/scripts/curl-polycall-server.in

@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+set -eu
+
+libexecdir="@LIBEXECDIR@"
+envfile="${CURL_POLYCALL_ENV:-@SYSCONFDIR@/curl-polycall/curl-polycall.env}"
+
+if [ -r "$envfile" ]; then
+    set -a
+    # shellcheck disable=SC1090
+    . "$envfile"
+    set +a
+fi
+
+exec "${PYTHON:-python3}" "$libexecdir/server.py" "$@"

package/scripts/curl-polycall.in

@@ -0,0 +1,60 @@
+#!/usr/bin/env sh
+set -eu
+
+base="${CURL_POLYCALL_URL:-http://127.0.0.1:8084}"
+
+usage() {
+    cat <<'USAGE'
+Usage:
+  curl-polycall server
+  curl-polycall health
+  curl-polycall command [ping|health|unknown]
+  curl-polycall attach PATH
+  curl-polycall detach PATH
+  curl-polycall demo
+
+Environment:
+  CURL_POLYCALL_URL  Base URL for client commands, default http://127.0.0.1:8084
+USAGE
+}
+
+case "${1:-help}" in
+    server)
+        exec "@BINDIR@/curl-polycall-server"
+        ;;
+    health)
+        curl --silent --show-error --fail "$base/"
+        printf '\n'
+        ;;
+    command)
+        command_name="${2:-ping}"
+        curl --silent --show-error --fail "$base/command?cmd=$command_name"
+        printf '\n'
+        ;;
+    attach)
+        if [ "${2:-}" = "" ]; then
+            printf 'curl-polycall attach requires a dependency path\n' >&2
+            exit 2
+        fi
+        curl --silent --show-error --fail "$base/micro/attach?path=$2"
+        printf '\n'
+        ;;
+    detach)
+        if [ "${2:-}" = "" ]; then
+            printf 'curl-polycall detach requires a dependency path\n' >&2
+            exit 2
+        fi
+        curl --silent --show-error --fail "$base/micro/detach?path=$2"
+        printf '\n'
+        ;;
+    demo)
+        exec sh "@EXAMPLESDIR@/curl.sh"
+        ;;
+    help|--help|-h)
+        usage
+        ;;
+    *)
+        usage >&2
+        exit 2
+        ;;
+esac

package/server.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlparse
+
+import ffi
+
+runtime: ffi.PolycallFFI | None = None
+
+
+class Handler(BaseHTTPRequestHandler):
+    def _send_json(self, payload: str, status: int = 200) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(payload.encode("utf-8"))
+
+    def do_GET(self) -> None:
+        if runtime is None:
+            self._send_json(json.dumps({"status": "NO", "message": "ffi runtime not loaded"}), 500)
+            return
+
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+
+        try:
+            if parsed.path == "/":
+                return self._send_json(json.dumps({
+                    "status": "YES",
+                    "message": "curl-polycall direct ffi server",
+                    "endpoints": [
+                        "/command?cmd=ping",
+                        "/command?cmd=health",
+                        "/command?cmd=unknown",
+                        "/micro/attach?path=build/bin/example.nsigii",
+                        "/micro/detach?path=build/bin/example.nsigii"
+                    ]
+                }))
+
+            if parsed.path == "/command":
+                command = query.get("cmd", [""])[0]
+                return self._send_json(runtime.command(command))
+
+            if parsed.path == "/micro/attach":
+                dep = query.get("path", [""])[0]
+                return self._send_json(runtime.attach(dep))
+
+            if parsed.path == "/micro/detach":
+                dep = query.get("path", [""])[0]
+                return self._send_json(runtime.detach(dep))
+
+            self._send_json(json.dumps({"status": "NO", "message": "unknown endpoint"}), 404)
+        except Exception as exc:
+            self._send_json(json.dumps({"status": "NO", "message": str(exc)}), 500)
+
+
+def main() -> None:
+    global runtime
+
+    host = os.environ.get("CURL_POLYCALL_HOST", "127.0.0.1")
+    port = int(os.environ.get("CURL_POLYCALL_PORT", "8084"))
+    try:
+        runtime = ffi.load()
+    except Exception as exc:
+        raise SystemExit(f"curl-polycall FFI load failed before serving: {exc}") from exc
+
+    print(f"curl-polycall serving http://{host}:{port}")
+    try:
+        HTTPServer((host, port), Handler).serve_forever()
+    except KeyboardInterrupt:
+        print("\ncurl-polycall stopped", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/src/polycall_ffi.c

@@ -0,0 +1,79 @@
+#define POLYCALL_FFI_EXPORTS
+#include "polycall_ffi.h"
+
+#include <ctype.h>
+#include <stdio.h>
+#include <string.h>
+
+static int has_non_space(const char *value) {
+    if (value == NULL) {
+        return 0;
+    }
+    while (*value != '\0') {
+        if (!isspace((unsigned char)*value)) {
+            return 1;
+        }
+        value++;
+    }
+    return 0;
+}
+
+static int dependency_path_is_valid(const char *dependency_path) {
+    if (!has_non_space(dependency_path)) {
+        return 0;
+    }
+    for (const unsigned char *cursor = (const unsigned char *)dependency_path;
+         *cursor != '\0';
+         cursor++) {
+        if (*cursor < 32U || *cursor == 127U) {
+            return 0;
+        }
+    }
+    return 1;
+}
+
+static int write_result(char *out_buffer, int out_buffer_len, const char *status, const char *message) {
+    if (out_buffer == NULL || out_buffer_len <= 0) {
+        return -1;
+    }
+    int written = snprintf(out_buffer, (size_t)out_buffer_len,
+                           "{\"status\":\"%s\",\"message\":\"%s\"}",
+                           status, message);
+    if (written < 0 || written >= out_buffer_len) {
+        return -2;
+    }
+    return 0;
+}
+
+int polycall_verify_command(const char *command, char *out_buffer, int out_buffer_len) {
+    if (!has_non_space(command)) {
+        return write_result(out_buffer, out_buffer_len, "NO", "empty command");
+    }
+
+    /* Verification-first example: accept only a small command vocabulary. */
+    if (strcmp(command, "ping") == 0) {
+        return write_result(out_buffer, out_buffer_len, "YES", "polycall pong via direct ffi");
+    }
+    if (strcmp(command, "health") == 0) {
+        return write_result(out_buffer, out_buffer_len, "YES", "ffi runtime healthy");
+    }
+
+    return write_result(out_buffer, out_buffer_len, "MAYBE", "command not registered");
+}
+
+int polycall_runtime_micro_attach(const char *dependency_path, char *out_buffer, int out_buffer_len) {
+    if (!dependency_path_is_valid(dependency_path)) {
+        return write_result(out_buffer, out_buffer_len, "NO", "invalid dependency path");
+    }
+
+    /* Attach means register/link dependency metadata at runtime; no execution here. */
+    return write_result(out_buffer, out_buffer_len, "YES", "micro dependency attached");
+}
+
+int polycall_runtime_micro_detach(const char *dependency_path, char *out_buffer, int out_buffer_len) {
+    if (!dependency_path_is_valid(dependency_path)) {
+        return write_result(out_buffer, out_buffer_len, "NO", "invalid dependency path");
+    }
+
+    return write_result(out_buffer, out_buffer_len, "YES", "micro dependency detached");
+}

package/src/polycall_ffi.h

@@ -0,0 +1,39 @@
+#ifndef POLYCALL_FFI_H
+#define POLYCALL_FFI_H
+
+#ifdef _WIN32
+  #ifdef POLYCALL_FFI_EXPORTS
+    #define POLYCALL_API __declspec(dllexport)
+  #else
+    #define POLYCALL_API __declspec(dllimport)
+  #endif
+#else
+  #define POLYCALL_API __attribute__((visibility("default")))
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Direct FFI boundary for libpolycall-style calls.
+ * This is intentionally NOT NSIGII logic and NOT a DOP adapter.
+ * It exposes stable C ABI functions that Python/Node/etc can load.
+ */
+POLYCALL_API int polycall_verify_command(const char *command,
+                                         char *out_buffer,
+                                         int out_buffer_len);
+
+POLYCALL_API int polycall_runtime_micro_attach(const char *dependency_path,
+                                               char *out_buffer,
+                                               int out_buffer_len);
+
+POLYCALL_API int polycall_runtime_micro_detach(const char *dependency_path,
+                                               char *out_buffer,
+                                               int out_buffer_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* POLYCALL_FFI_H */