Shadow Man NULL boundary capture mechanism
Historical source last updated, 2026-10-23. Runtime and implementation claims below describe that dated source; see current app notes and source for subsequent changes.
Capture and stop contract
tools/shadow-man-null-capture.cjs arms existing set_trace_eip_range for
0x004015d4 and clears the competing EIP breakpoint. The host log_eip callback
runs synchronously before that decoded block, including recursive WAT $run. It copies all eight GPRs, EIP, 128 guest stack bytes at ESP-32, and 64 loaded
guest code bytes at 0x004015d4 through read-only exports. No region addresses
are inferred. Immutable hex strings, metadata, sequence, schema version, stop
policy and a SHA256 seal form the record. The seal detects accidental changes;
it is not authentication. Only the first matching block is retained.
Default mode stops on that block. tools/shadow-man-null-preload.cjs wraps the
final WebAssembly.instantiate(Module, imports) call used by pinned test/run.js,
so runner import construction cannot overwrite the observer. It opens an
exclusive output file, synchronously writes and fsyncs each JSONL record and
exits the dedicated OS process with 86 at a terminal event. Terminal failure
also exits, even if final-record writing fails. Other exit statuses/missing
terminal records are capture failure. The guest is abandoned; this is not a
recoverable pause. An external watchdog is still required for a never-reached
address, guest spin, or OS failure. No export-level JS wrapper is claimed to
intercept recursive $run.
For a separately authorized dedicated main-thread target process, use the
existing installed Node in place, preload with --require=.../tools/shadow-man-null-preload.cjs,
set SHADOW_NULL_OUTPUT to an absent output filename, and supply the retained
canonical --wasm=PATH. Do not use --break, --trace-at, --trace-eip, guest
workers, or a spawned-child runner with this adapter. The adapter checks the
actual module file hash/size; missing required exports fail before guest work. This task did not inspect the historical wasm export inventory. Child launcher
orchestration is outside this single-process adapter: choose the target process
explicitly in the next runtime assignment, rather than inherit it through an
installer tree. No complete guest/VFS/runtime command was invented here.
Extra boundary hook and readiness
Existing interfaces cannot expose sender saved locals, private pump state or
first zero before sender restoration. The smallest source addition uses only
existing host.log_eip, with negative event tags while explicitly armed by
set_null_diag(1). It allocates no linear-memory region and adds no mandatory
host import. Normal behavior is unchanged with the flag off; no modal ownership,
frame cleanup, sender restoration or dispatch policy is repaired.
| Event | Exact observation |
|---|---|
| -1 sender-pre | Saved EIP/ESP, current GPRs before pushing the synchronous callback frame, after invocation allocation |
| -2 sender-before-restore | Saved EIP/ESP and current registers immediately after nested run ends, before identity checks, depth leave and restoration |
| -3 modal-frame-consume | Current completion ESP before reading previous pump from ESP+4..20, after teardown |
| -4 modal-frame-complete | Current EIP/ESP after the 24-byte frame adjustment; savedEsp identifies the consumed frame; before ended/result reset |
| -5 first-zero | $run observes EIP==0, before returning to its sender; unconditional trap after callback if the host returns |
| -6 overflow | Attempted 33rd source event; trap even if host returns |
For each source event the host copies the same registers/stack/code plus saved EIP/ESP, private pump HWND/return/ended, shared pump HWND/ended, current invocation token/root and synchronous depth. Token/root are decimal strings preserving 64-bit identity. They describe current state, not an inferred sender-owned token. Saved fields on first-zero are zero/not applicable; earlier sender events carry the saved caller pair. Modal completion records the actual frame after sentinel adjustment, not the initial CACA0004 entry ESP. No handler exit is labelled a guest modal return. Pump state may already have changed during teardown; the record reports its actual value at each named site.
Host records are capped at 32, including the block; the independent source cap
is 32 source events. Reaching either limit is terminal failure. In the explicitly
selected SHADOW_NULL_UNTIL_ZERO=1 mode, the first block is retained and execution
is authorized to continue only until first-zero or the record cap. This mode
requires SHADOW_NULL_REVISED_SHA matching the new diagnostic module, and
requires its diagnostic exports. Historical module identity stays separate in
metadata. Do not present a revised module as historical canonical execution.
Verification
Run node test/test-shadow-man-null-capture.cjs in this checkout. Exit 0;
tests.json (historical artifact: shadow-man-null-capture-mechanism-20261023/tests.json) lists checks. The 902-byte native fixture uses an 8 MiB arena. It executes the actual source
hook declarations, extracted trace predicate and zero branch against fixture
register/pump globals, including recursive callback-to-host capture. It does
not execute complete production handlers or simulate the Shadow Man incident.
Positive/rejecting tests cover address filtering, register/stack/code copies, immutability after memory changes, terminal block stop before a native marker, missing/wrong address, missing registers/bytes, changed stack, continued execution, missing exports, retention failure, record quota, default-off hook, first-zero and source quota traps with a returning host observer, and metadata callback values. The exact pinned runner instantiate call form is executed; full test/run.js is not launched. A real child Node process loads the preload, flushes source events and exits 86 before its continuation marker. The fixture and driver are retained for review; compiler support files were copied unchanged only for this focused test, and are not proposed changes.