Native IPC v1 — Pi math worker boundary
Status: The repository contains the v1 wire codec, transport-neutral C client, VM-owned worker-handle lifecycle, and a persistent Python reference worker/supervisor. The pieces are not yet a fully connected SLeeLa bytecode worker-dispatch feature.
Architecture and ownership
There are four distinct layers:
- Wire codec: encodes and validates the 24-byte frame header, scalar values, request payloads, and canonical signed base-1e9 limbs.
- C transport client:
native_ipc_client.c/.hperforms handshake and request/response exchanges through caller-provided exact-read and exact-write callbacks. It does not itself create a process. - Python reference supervisor:
tools/sleela-ipc-worker.pylaunches a persistent child process, verifies the launched executable hash, applies cwd/environment policy, handles request deadlines, captures bounded stderr, and owns shutdown/termination. - VM worker ownership: the VM core provides 64 opaque worker slots with generation-protected handles and leases. Registration accepts an already created and authorized worker; it is not a launch or authorization path.
The VM handle API is exposed through slvm_ipc_worker_register,
slvm_ipc_worker_acquire, slvm_ipc_worker_release, and
slvm_ipc_worker_close. Close prevents new leases, waits for existing leases
to drain, invalidates the generation, and invokes the close callback outside
the table lock. VM shutdown closes registered workers, and new registration is
rejected once shutdown begins.
The reserved Native IPC bytecode opcodes remain fail-closed. The supervisor adapter and capability policy that would connect bytecode dispatch to the process worker are not yet complete. Do not treat handle registration as process authorization.
Why a separate boundary is needed
SLeeLa syntax 3.0 already has host-authorized nativeOpen,
nativeCall, and nativeClose operations for a typed shared-library ABI
inside the VM process. That ABI deliberately excludes arrays, structs,
object handles, pointers, and raw SLValue objects. Large Pi integers need a
separate process boundary with explicit serialization—not pointers into VM
memory.
Frame layout
All fields are encoded explicitly in little-endian order; C struct layout is never sent over the wire. Header size is 24 bytes:
| Offset | Width | Field |
|---|---|---|
| 0 | 4 | Magic SLIP |
| 4 | 2 | Version (1) |
| 6 | 2 | Kind: request=1, response=2, cancel=3, hello=4, hello-ack=5 |
| 8 | 8 | Request ID |
| 16 | 4 | Payload length |
| 20 | 4 | Signed status |
Maximum payload is 16 MiB. The scalar codec supports null, boolean, signed int64, binary64 double, and length-delimited UTF-8. Strings decoded from borrowed spans must be copied before their receive buffer is reused; validate UTF-8 before constructing a SLeeLa String. Unknown tags, bad magic/version/ kind, truncated values, invalid booleans, and oversized payloads are rejected.
Request and big-integer payloads
The request payload is a uint16 method-name length, method bytes, uint16 argument count, then encoded scalar arguments. The implementation rejects empty/oversized names, malformed UTF-8, truncated values, and trailing bytes. Successful responses contain one encoded scalar value; nonzero status carries a bounded UTF-8 diagnostic.
The C codec also defines a canonical signed base-1e9 representation:
- Base: 1,000,000,000.
- Limbs: unsigned 32-bit little-endian, least-significant limb first.
- Explicit limb count and sign (positive=1, negative=2 on wire).
- Zero has one zero limb and positive sign.
- Redundant high zero limbs are forbidden.
- Count, byte length, limb range, and configured maximums are checked.
Current integration distinction: the Python reference worker's
bigint.add, bigint.sub, and bigint.mul methods currently accept
decimal-string scalar arguments. The canonical base-1e9 limb codec is not yet
the payload path used by those methods. Do not claim that Pi limb arrays have
already crossed the worker boundary.
Reference methods currently include math.ping, math.capabilities,
bigint.add, bigint.sub, bigint.mul, and pi.compute. The worker's
Pi implementation uses Python arbitrary-precision integers and Chudnovsky
binary splitting.
Process and security contract
The Python supervisor launches with an argv vector and shell=False, verifies
the SHA-256 digest of the resolved argv[0], uses an explicit working
directory and environment allowlist, and captures stderr up to a configured
bound. It applies a request timeout and on shutdown sends a cancel frame,
waits briefly, then terminates or kills and reaps the child if needed.
The current integrity check covers the launched executable path. When the worker is an interpreter plus script, the script and any other executable inputs also need an explicit integrity policy before this is treated as a production authorization boundary. The host must own the allowlist and policy; source annotations cannot grant capabilities.
A worker failure after a request is accepted is an error, not a silent interpreter fallback. Fallback is safe only for an explicit NOT_HANDLED response before the operation has performed side effects.
Verification
The Native Drive workflow runs:
python -m unittest discover -s tools/tests -p "test_sleela_ipc_worker.py" -v
That suite checks handshake and multiple requests, scalar bigint examples, 50-digit Pi output, a 20,000-digit Pi output length/prefix/SHA-256 fixture, executable-integrity rejection, payload bounds, and malformed frame magic.
The 20,000-digit fixture validates the Python reference worker. It does not
prove SLeeLa VM/sleelactl integration or provide a performance benchmark.
The C codec/client smoke tests exercise their own interfaces; the VM handle
lifecycle smoke test exercises ownership and leases, not process transport.
Before production bytecode integration, add fault tests for fragmented reads and writes, multiple frames per read, malformed/oversized frames, invalid UTF-8, duplicate outstanding IDs, timeout/cancel, worker crash, output flood, authorization denial, executable/script tampering, cleanup/reaping, and cross-platform behavior. Then differential-test the chosen big-integer representation against the VM kernel and run the actual SLeeLa Pi workload against an independent 20,000-digit reference.
Portable stdio stream adapter
native_ipc_stdio.h/.c implements the existing exact-read/exact-write callbacks
over caller-supplied FILE* streams. The host retains stream ownership and is
responsible for connecting them to an authorized worker's stdin/stdout pipes.
The adapter is blocking: it does not launch or supervise a process, enforce
deadlines, cancel requests, terminate children, or reap them.
The focused smoke test is impl/tests/native_drive/native_ipc_stdio_smoke.c.
It checks binary exact-transfer, output flush, and truncated-read rejection.
A dedicated GitHub Actions workflow runs this test on Ubuntu, macOS, and
Windows. Passing that smoke test validates only the stream adapter; it does
not establish end-to-end VM IPC, worker supervision, or Pi dispatch.
Manual POSIX command:
cc -std=c11 -Wall -Wextra -Werror impl/native-drive/native_ipc_stdio.c \
impl/tests/native_drive/native_ipc_stdio_smoke.c -o native-ipc-stdio-smoke
./native-ipc-stdio-smoke
Windows/MSVC command (from an initialized developer shell):
cl /nologo /std:c11 /W4 impl/native-drive/native_ipc_stdio.c impl/tests/native_drive/native_ipc_stdio_smoke.c /Fenative-ipc-stdio-smoke.exe
.\\native-ipc-stdio-smoke.exe