ext_net: raw TCP/UDP sockets as tape-recorded nondeterministic inputs

[InauguralPhysicist]

Why. No raw sockets is the biggest "real standalone program" blocker on the roadmap — network protocols are only writable via the canned HTTP extension. The differentiating design: every read/accept/timeout enters through the trace-tape seam, so EigenScript becomes the only language whose stdlib gives network programs record/replay debugging by default — "replay last night's flaky failure exactly" is something Go's net and Python's socket cannot say.

What.

• src/ext_net.c (opt-in extension like ext_http): net_listen / net_accept / net_send / net_recv / net_dial, with timeouts.
• Every nondeterministic result is a tape record per the eigenscript-extend-vm nondet-builtin checklist — recording and replay are part of the definition of done, not a follow-up.
• examples/net_echo.eigs.
• Forcing function: liferaft nodes talking over real sockets, a seeded kill replayed byte-for-byte (its sim harness is the transcript oracle).
• This is also the upstream seam EigenOS M13 (e1000 NIC) will eventually target.

Acceptance. Echo example records under EIGS_TRACE and replays without the network present; liferaft real-socket demo green; extension absent from the default 420K build.

Effort: weeks. Source: 2026-07-04 survey (stdlib dimension).

[InauguralPhysicist]

Design grounding from the 2026-07-10 burndown (ready to implement next session):

Pattern — src/ext_net.c mirrors ext_http's opt-in shape (EIGENSCRIPT_EXT_NET=0 default, own Makefile variant + compile-check target). Handles go in the process handle table (HANDLE_* enum) like Store/Thread/Channel, drained by handle_table_drain.

Tape semantics (the definition-of-done half):

• net_recv / net_accept / net_dial: TRACE_NONDET_TAKE first statement, TRACE_NONDET_RECORD at every return — replay must never touch a socket (the TAKE short-circuit is what makes "replays without the network present" true).
• net_send: side-effecting — record its RESULT (bytes-sent/status) and under replay serve it WITHOUT sending. This is the send-suppression rule; document it in TRACE.md's non-replayable section as the deliberate contrast to proc_* (proc_* builtins are invisible to trace/replay — EIGS_REPLAY re-runs live subprocess side effects #148): sends are suppressible because the tape pins the observable world's responses.
• Handle numbering must be deterministic by construction (table slot order), or recorded — decide at implementation; slot-order is likely free since the scheduler is deterministic (Deterministic cooperative task layer that rides the trace tape (task_spawn / task_send / task_recv / task_yield) #408).
• Timeouts return a distinct outcome value that records like any other result (virtual-time integration with the task layer's sleeper machinery — see Deterministic cooperative task layer that rides the trace tape (task_spawn / task_send / task_recv / task_yield) #408 inc3's zero-N-record clock discipline; a real-socket timeout IS nondet, unlike the virtual clock).
• Tape-first review before merge (standing veto: no untraced I/O), then the eigen-determinism-verification adversarial pass AFTER the claim ships.

Acceptance train: examples/net_echo.eigs records under EIGS_TRACE and replays with the network down → suite section; then the liferaft real-socket demo (downstream repo) as the forcing function — a seeded kill replayed byte-for-byte against its sim-harness transcript oracle.

🤖 Generated with Claude Code

[InauguralPhysicist]

TCP half landed in #788 (merged, all gates green).

What shipped, against the design comment above:

• src/ext_net.c behind EIGENSCRIPT_EXT_NET=1 (make net; in no default build; also folded into make asan-http so CI sanitizes it) — net_listen / net_port / net_accept / net_dial / net_recv / net_send / net_close, poll-based timeouts.
• Tape semantics as specified: TAKE-first/RECORD-at-every-return on the whole family; send-suppression documented in TRACE.md as the deliberate contrast to proc_* (proc_* builtins are invisible to trace/replay — EIGS_REPLAY re-runs live subprocess side effects #148); timeouts are a distinct recorded outcome (null). One addition over the sketch: environment failures are recorded values (null/-1/empty buffer), never live-path-only raises — a catch would otherwise 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).
• Handles are HANDLE_NET rows in the process handle table, drained by handle_table_drain. Ids are recorded on the tape rather than relying on slot-order determinism.
• Acceptance met: examples/net_echo.eigs records under EIGS_TRACE and replays byte-identically with zero socket-family syscalls (strace-verified). Suite section [125] pins the byte-diff and a 17-record tape accounting.

Still open here:

• UDP (title scope; nothing consumes it yet — the forcing-function rule says wait for the consumer).
• liferaft real-socket demo — the downstream acceptance train: nodes over real sockets, a seeded kill replayed byte-for-byte against the sim-harness transcript oracle. Needs a released EigenScript carrying ext_net before liferaft can pin it (consumers pin releases, not main).
• Adversarial pass by the determinism-verification role after the claim ships in a release (injection sweeps, N-record accounting).
• v1 residuals noted in the PR: handle structs aren't refcounted (cross-thread net_close racing a blocking net_recv — same exposure class as Channel/Thread handles; single-threaded use is the v1 contract), and net_dial's DNS resolution blocks before the connect timeout applies.

🤖 Generated with Claude Code