ext_net: raw TCP sockets as tape-recorded nondeterministic inputs (#414)

[InauguralPhysicist]

Part of #414 (TCP half; UDP and the liferaft real-socket demo stay open there).

What

src/ext_net.c — an opt-in extension in ext_http's shape (EIGENSCRIPT_EXT_NET=1, in no default build): net_listen / net_port / net_accept / net_dial / net_recv / net_send / net_close, with poll-based timeouts. Sockets are HANDLE_NET rows in the process handle table, drained at exit.

The tape contract (the definition of done, not a follow-up)

• Every nondet outcome — accepted connections, received bytes, bytes-sent counts, dial results, kernel-assigned ephemeral ports — is TRACE_NONDET_TAKE/RECORD-wrapped. Under EIGS_REPLAY the TAKE short-circuits before any socket call: the replay run performs zero socket-family syscalls (strace-verified; live run: 6).
• Environment failures are recorded values (null / -1 / empty buffer), never live-path-only raises — a catch cannot desync the N-record stream (the read_bytes_buf: over-cap read silently returns null (misleading downstream errors) + no opt-in for files >10MB #601 lesson). Argument-shape errors raise deterministically before the tape boundary.
• net_send is a suppressed recorded write (the mkdir rule): recorded count served under replay, nothing written. Documented in TRACE.md as the deliberate contrast to the proc_* builtins are invisible to trace/replay — EIGS_REPLAY re-runs live subprocess side effects #148 subprocess family.
• net_recv caps at 8192 bytes/call so every N record fits the 64 KiB budget (the audio_capture_read discipline).

Acceptance

$ EIGS_TRACE=t.tape  eigenscript examples/net_echo.eigs > a
$ EIGS_REPLAY=t.tape eigenscript examples/net_echo.eigs > b
$ diff a b        # byte-identical, no network touched

Suite section [125] (probe-gated, runs under make net and make asan-http in CI): 25 loopback echo checks — a single-threaded program is both ends via the listen backlog — plus record→replay byte-diff and a pinned 17-record tape accounting check.

Gates

• release 3280/3280 · net 3308/3308 · ASan 3284/3284 · asan-http(+net) 3408/3408 — all 0 failed, leak tally at floor 0
• ext_net now compiles into make asan-http, so the extension stays sanitizer-covered in CI
• http / gfx / lsp / freestanding compile checks green

Residual (noted for the tape-first review)

• Handle structs aren't refcounted: a cross-thread net_close racing a blocking net_recv is the same exposure class as existing Channel/Thread handles. Single-threaded use is the v1 contract.
• getaddrinfo in net_dial blocks without a timeout (DNS is resolved before the nonblocking-connect timeout applies).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an opt-in ext_net extension that exposes raw TCP sockets while preserving EigenScript’s trace/replay determinism by routing all nondeterministic outcomes through the trace tape (TAKE/RECORD), and integrates it into builds, docs, CI, and the test suite.

Changes:

• Introduces src/ext_net.c (+ private header) implementing net_listen/net_port/net_accept/net_dial/net_recv/net_send/net_close with poll-based timeouts and trace-tape wrapping.
• Adds a dedicated test file plus a new probe-gated suite section that verifies record→replay byte identity and a pinned N-record count.
• Wires the extension into build targets, CI, lint’s builtin-name surface, and user docs/CHANGELOG.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_net.eigs	New single-process loopback tests for the net_* builtins, including timeout/EOF/value behavior expectations.
tests/run_all_tests.sh	Adds probe-gated section [125] running net tests and enforcing record→replay output equality + pinned tape accounting.
src/lint.c	Extends lint’s builtin-name sets to include EIGS_NET_BUILTINS.
src/ext_net.c	New extension implementation: TCP sockets + tape-wrapped nondeterminism + handle-table integration.
src/ext_net_internal.h	Private extension header defining EigsNetSock for handle-table storage/drain.
src/ext_names.h	Adds the EIGS_NET_BUILTINS macro list.
src/eigenscript.h	Adds EIGENSCRIPT_EXT_NET flag and HANDLE_NET handle type.
src/builtins.c	Registers net builtins when enabled; drains HANDLE_NET rows at teardown.
README.md	Documents make net build target.
Makefile	Adds net target; includes ext_net in full build and asan-http build.
examples/net_echo.eigs	New example program demonstrating record/replay with no network on replay.
docs/TRACE.md	Documents ext_net’s tape contract and replay suppression of net_send.
docs/BUILTINS.md	Documents the new net_* builtins and their semantics.
CHANGELOG.md	Adds an Unreleased entry describing ext_net and its trace/replay guarantees.
.github/workflows/ci.yml	Adds make net + full-suite run for the net variant.

Suppressed comments (3)

src/ext_net.c:226

• net_dial doesn’t check fcntl(F_GETFL) / fcntl(F_SETFL) results when switching the socket to nonblocking. If either fails, connect() may block indefinitely (breaking the timeout guarantee), or the fd may end up in a mode the later send/recv paths don’t handle (e.g., EAGAIN).

    int flags = fcntl(fd, F_GETFL, 0);
    fcntl(fd, F_SETFL, flags | O_NONBLOCK);
    int rc = connect(fd, res->ai_addr, res->ai_addrlen);

src/ext_net.c:243

• net_dial restores the original fd flags with fcntl(fd, F_SETFL, flags) but doesn’t check for failure. If the restore fails, subsequent net_send/net_recv may behave unexpectedly (e.g., nonblocking EAGAIN) since those paths assume a blocking socket plus poll.

    fcntl(fd, F_SETFL, flags);

src/ext_net.c:259

• net_recv parses max_bytes and timeout_ms with net_num_at, which means a non-numeric timeout_ms silently becomes -1 (infinite block) and a non-numeric max_bytes becomes 0 (then raises EK_VALUE). For consistency with the contract that argument-shape errors raise deterministically before the tape boundary, these should be validated as numbers explicitly.

    int max = net_num_at(arg, 1, 0);
    int timeout_ms = net_num_at(arg, 2, -1);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.