Automattic / Automattic/kandelo
Design versioned fork-save metadata with pre-write bounds
- Dominant language
- TypeScript
- Stars
- 31
- Forks
- 15
- Avg merge
- 11h 7m
- Merged PRs (30d)
- 80
Description
## Why this is needed
PR #907 landed the current truthful-failure boundary: Kandelo checks the main-process, pthread, and active side-module continuation buffers after unwind and refuses to create a child when a fixed 16 KiB reserve was overrun. That keeps corrupted state from becoming a child, but the instrumented module has already written outside its reserve by the time the host can diagnose it.
PR #862 proved the real user impact with GTK/LXDE and preserved useful measurements, but its ABI-17 opt-in frame-counter design is rejected as written. It assumes a cursor remains trustworthy after an overrun, does not make every main/pthread/side-module write safe before it happens, and is based on an obsolete ABI epoch. Mechanically rebasing it would preserve the wrong contract.
This issue keeps the investigation and starts the replacement from current `main`.
## Design direction
Define one versioned fork-instrumentation metadata contract that lets the instrumented module and host agree on buffer placement, capacity, header layout, and frame requirements before any continuation write crosses its bound.
The design should:
- publish explicit, versioned metadata instead of inferring capacity or frame state from a possibly corrupted cursor;
- check header, global snapshot, auxiliary scratch, and each frame write before the store occurs;
- fail before modifying memory outside the declared save region;
- cover the process main module, pthread continuations, and fork-capable side modules with the same rules;
- preserve correct NORMAL/UNWINDING/REWINDING transitions and nested/side-module replay ordering;
- define how a caller learns the required capacity and whether retry/growth is possible without partially unwinding twice;
- reject missing, stale, or incompatible metadata loudly;
- keep Node.js and browser behavior identical apart from documented host boundaries; and
- retain #862's real LXDE reproduction as acceptance evidence, not as a package-specific workaround.
Do not revive the `--frame-counter` opt-in or ABI-17 wording without a new ABI audit. Treat the replacement as ABI-changing until that audit proves otherwise.
## ABI and artifacts
The fork export/metadata format, save-buffer layout, host-reserved regions, generated host constants, and VFS/package ABI binding are all ABI surface. If the design changes any of them, update `ABI_VERSION`, `abi/snapshot.json`, generated TypeScript/C evidence, and the fork/ABI docs atomically. Rebuild and republish every affected ABI-bound package and image through the normal package path; stale artifacts must fail rather than receive a compatibility shim.
## Completion evidence
- [ ] Focused instrumenter tests for wasm32 and wasm64, including exact-boundary and one-byte-over cases.
- [ ] Pre-write failure tests proving adjacent channel/control memory remains unchanged.
- [ ] Main-process, pthread, and fork-capable side-module coverage on Node.js and a real browser.
- [ ] Full fork-instrument suite and ABI snapshot/version check.
- [ ] Host typecheck, full Vitest, browser asset check, focused Chromium, non-slow browser suite, and manual `./run.sh browser` verification.
- [ ] Relevant libc, POSIX, and Sortix conformance consideration for fork/process behavior.
- [ ] Rebuilt affected packages and VFS images for the chosen ABI, with current cache/index evidence.
- [ ] Real LXDE validation that opens a second application through the original double-fork path without an overrun or hidden fallback.
- [ ] Node and browser performance measurement for any hot-path or memory-size claim, or an explicit statement that no performance claim is made.
Related: #907, #862, #845.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start from current main and PR #907's continuation-buffer checks, then review ABI_VERSION, abi/snapshot.json, the generated TypeScript/C evidence, and the fork/ABI docs. Use the focused instrumenter tests for wasm32/wasm64 and the listed Node.js, browser, ABI, and LXDE checks to define completion; done requires the full ABI, pre-write safety, package, and real-browser evidence described here.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, node.js, typescript, wasm
- Domain
- compilers, operating-systems, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100