node:child_process: 57 surface methods still stubbed (ChildProcess.kill/disconnect/send + stdio + execFile)

[proggeramlug]

Summary

node:child_process is at ~4% parity. #1780 closed via #1955 etc. (async spawn reactor, fork+IPC, exec/spawnSync encoding parity), but 57 tests still fail with "value is not a function" — large parts of the API surface remain stubbed.

Examples: test-child-process-advanced-serialization-largebuffer.js, test-child-process-advanced-serialization-splitted-length-field.js, test-child-process-can-write-to-stdout.js.

What to do

Audit the child_process surface beyond what #1955 covered: ChildProcess instance methods (kill, disconnect, unref, ref, send), stdio socket wiring (stdin.write, stdout.on('data'), stderr.pipe), execFile/execFileSync paths, advanced serialization for IPC. Pair with #1852's net work where stdio sockets share lifecycle.

This is the largest single-API "stubbed-method" cluster in the radar — fully implementing it would lift c_p from 4% to a meaningful number.

Context: #800 sweep, perry 0.5.1032. Follow-up to #1780 (now closed).

[proggeramlug]

Triage: the "57 stubbed methods" count is stale — common surface now passes

On current main (post #1955 and the subsequent node:net/child_process work) the common child_process surface matches Node byte-for-byte in direct comparisons (node vs the Perry-compiled program):

• spawn ChildProcess: pid/kill/ref/unref are functions, send/disconnect correctly undefined (no IPC), connected=false, killed boolean, exitCode/signalCode/spawnfile correct; stdout.on('data'), stderr, and close all fire.
• stdin: child.stdin.write(...) + .end() reach the child (echo round-trips); child.stdio is an array with the expected socket objects.
• fork + IPC: send/disconnect/connected work, 'message' and 'disconnect' events fire, JSON ('json') serialization round-trips.
• spawnSync/execFileSync/execSync/exec/execFile: status/stdout/stdio/pid/signal/output all match.

So the bulk of the original 57 "value is not a function" failures appear already closed; the radar count predates that work (issue cites perry 0.5.1032).

The one concrete remaining gap I could reproduce

serialization: 'advanced' loses type fidelity: a Buffer sent over fork IPC arrives as a plain object under Perry vs a real Buffer under Node:

fork(child, [], { serialization: 'advanced' }); child.send({ buf: Buffer.from([1,2,3,4,5]) })
// Node child:  { isBuf: true,  len: 5, first: 1 }
// Perry child: { isBuf: false, len: -1, first: -1 }

Perry's IPC is newline-delimited JSON (child_process/fork.rs, reactor.rs::cp_ipc_send), and the serialization option is ignored. Implementing 'advanced' is non-trivial here because forked children run under node (exec_path defaults to "node"), so the wire format would have to match V8's structured-clone serialization (length-prefixed binary, versioned) — which is what test-child-process-advanced-serialization-* exercises (largebuffer, splitted-length-field framing).

Suggested re-scope: close out the already-working surface (optionally lock it in with a hand-authored node-suite case), and track advanced/V8 IPC serialization as the focused remaining sub-issue.

[proggeramlug]

Addressed the concrete remaining gap (serialization: 'advanced' IPC) in #2453.

Confirmed the triage: the common surface (spawn streams, stdin/stdout/stderr, kill/ref/unref/send/disconnect, fork+json IPC, exec*/spawnSync) was already byte-for-byte. The PR adds a V8 structured-clone codec (child_process/v8_serde.rs) on the parent side so fork(..., { serialization: 'advanced' }) interoperates with the real node child — Buffers/TypedArrays keep full type fidelity in both directions, including the largebuffer and splitted-length-field framing cases. Verified byte-for-byte vs node --experimental-strip-types.

[andrewtdiz]

Current PR-cut index for this tracker after the merged child-process execution work:

The original “57 surface methods still stubbed” snapshot is stale. Merged PRs have added streaming spawn(), fork() IPC, exec / execFile / sync result and error fields, captured callable exports, and advanced IPC serialization. The remaining work should be treated as focused leaves under a node:child_process: subprocess lifecycle and setup parity cut boundary.

Open child issues:

• node:child_process: honor spawn and exec option semantics beyond cwd/env/shell #2555 - node:child_process: honor spawn and exec option semantics beyond cwd/env/shell
• node:child_process: validate command, file, and args inputs #3079 - node:child_process: validate command, file, and args inputs
• node:child_process: implement subprocess[Symbol.dispose] lifecycle method #2556 - node:child_process: implement subprocess[Symbol.dispose] lifecycle method
• node:child_process: expose _forkChild IPC bootstrap helper #2717 - node:child_process: expose _forkChild IPC bootstrap helper
• node:child_process: honor subprocess.send callback and closed-channel semantics #3316 - node:child_process: honor subprocess.send callback and closed-channel semantics

Related but usually separate unless the PR intentionally adds a compiled-Perry child IPC harness:

• node:process: implement child-side IPC channel surface #2529 - node:process: implement child-side IPC channel surface

Evidence anchors:

• docs/runtime-parity-gaps.md:1701-1734 still lists many ChildProcess members/events as missing; some rows are stale because current source now constructs live stdio streams, lifecycle fields, and event methods.
• crates/perry-runtime/src/child_process/reactor.rs:405-515 constructs streaming spawn() ChildProcess objects with kill, ref, unref, stdio streams, lifecycle fields, and spawnargs / spawnfile.
• crates/perry-runtime/src/child_process/fork.rs:64-129 constructs forked ChildProcess objects with stdio, send, disconnect, connected, channel, and IPC launch setup.
• crates/perry-runtime/src/child_process/mod.rs:1116-1124 documents that only cwd, env, and shell options are currently applied; stdio, timeout, maxBuffer, and related options remain ignored.
• crates/perry-runtime/src/child_process/mod.rs:873-882 implements subprocess.send as a two-argument closure that ignores callback/options/handle behavior and always returns true.
• test-files/test_parity_child_process.ts:101-155 probes ChildProcess shape/events and explicitly skips subprocess[Symbol.dispose]().
• crates/perry-api-manifest/src/entries.rs:2615-2629 registers the public child-process execution helpers plus ChildProcess / Stream, but does not register _forkChild.

Suggested PR boundaries:

• setup validation + deterministic option behavior for spawn / exec / execFile / sync helpers (node:child_process: honor spawn and exec option semantics beyond cwd/env/shell #2555, node:child_process: validate command, file, and args inputs #3079), or
• subprocess lifecycle / IPC surface polish around disposer, _forkChild, and send observable semantics (node:child_process: implement subprocess[Symbol.dispose] lifecycle method #2556, node:child_process: expose _forkChild IPC bootstrap helper #2717, node:child_process: honor subprocess.send callback and closed-channel semantics #3316).

Non-goals: do not redo merged execution work from PRs 1858, 1926, 1955, 2170, 2453, or 2681; do not use this tracker for unrelated node:process APIs except the explicitly related child-side IPC follow-up #2529; do not batch with broad subsystem rewrites or unrelated modules.

[andrewtdiz]

Current-main curated child_process baseline at 22824ba90 is green for the deterministic execution fixtures:

$ ./run_parity_tests.sh --suite node-suite --module child_process
Parity Pass:   7
Parity Fail:   0
Compile Fail:  0
Report: /private/tmp/perry-node-compat-main/test-parity/reports/parity_report_20260531_152659.json

Covered in this module run:

async/captured-spawn-optional-args
async/exec-encoding-buffer
async/exec-error-fields
sync/nonzero-throw
sync/spawn-sync-encoding-buffer
sync/spawn-sync-result-fields
sync/sync-encoding-buffer

This supports keeping the original broad “57 stubbed methods” snapshot narrowed to the existing leaf issues. It does not close the remaining option-semantics/default-export/_forkChild/disposer work; those surfaces are either not covered by this curated module slice or are tracked by the open child issues listed above. No Test262 coverage was involved.