Automattic / Automattic/kandelo

Design versioned fork-save metadata with pre-write bounds

Open
#922 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.