pcbjam/docs/features/async/14-open-settle-gate.md

# 14 — The open-settle gate: prod "indirect call signature mismatch" at board load

## Symptom

Intermittent, prod, mostly Firefox: loading an editor URL (observed on
`…/Arduino Mega 2560.kicad_pcb`) sometimes fails the boot with

```
Error: RuntimeError: indirect call signature mismatch
```

right around the `[collab] maybeStartCollab gate:` console line. Previously
suspected (wrongly) to be related to spaces in filenames.

## Root cause

Three stacked defects:

1. **The "file loaded" signal was a no-op.** `openFileInTool` fires
   `Module.kicadOpenFile(path)` — which runs `OpenProjectFiles` under Asyncify,
   i.e. the embind call unwinds back to JS long before the load finishes — and
   then polls `schematicLoaded()`: *"title is non-empty and does not contain
   'untitled'"*. But pcbnew's pre-open title is `"PCB Editor"` (a fresh frame;
   `PCB_EDIT_FRAME` ctor title), and a real project's title never contains
   "untitled" at any point. The poll therefore passed **on the first check**,
   while the load had barely started. (The heuristic only ever waited for the
   `@local` new-file flow, whose files are literally named `untitled.*`.)

2. **`driveProjectIntoTool` ignored the result** — even an honest `"failed"`
   (60 s timeout) let the boot IIFE continue.

3. **Everything after it drives bare embind entries that walk the model.**
   `maybeStartCollab` → `attachKicadCollab` → `seed()` →
   `kicadCollabSnapshotItems()` (inline board walk + per-item `Format()`), then
   `bindKicadPresence` (GAL `VIEW_OVERLAY` bind). These run while the
   `kicadOpenFile` chain is still **parked mid-mutation of the same
   BOARD/SCH_SCREEN** (progress-reporter yields, futex yields, lib bridges). A
   virtual call that lands on a half-built item reads a garbage vtable slot →
   `call_indirect` hits a wrong-typed table entry → Firefox reports
   `indirect call signature mismatch`. The boot IIFE catches it →
   `Error: RuntimeError: …` in the status overlay.

This is the same reentrancy class as two already-fixed bugs — the wxWidgets
**dispatch interlock** (`wxwidgets/docs/wasm/dispatch-interlock.md`: no event
dispatch while another chain is parked) and drift-trio **finding #10b**
(`kicadCollabFiberBusy`: no bare-embind scratch save while a collab fiber is in
flight) — but through the one entry family neither guard covers: **web-shell
JS → embind calls during the open park**. Timing-dependent, hence "sometimes";
slow Firefox loads widen the window enormously; filename spaces were never
involved.

## Fix

Three layers, mirroring the shape of the earlier interlocks:

1. **Truthful completion signal** — `wasm/bindings/open_gate.h`:
   `pcbjam_open::BusyGuard`, an RAII counter on `kicadOpenFile`'s C++ stack
   frame. Under Asyncify an unwind does not run destructors and a rewind
   resumes past the constructor, so the count is held across every park and
   drops exactly when `OpenProjectFiles` truly returns (the same primitive as
   `wxWasmDispatchGuard`). Exported as `Module.kicadOpenFileBusy()` from all
   four `kicadOpenFile` definitions (pcbnew / eeschema standalone, merged
   kicad_editor, pl_editor), mirroring the `kicadCollabFiberBusy` probe.

2. **JS waits for it** — `open-flow.ts` `waitForOpenSettled()`: after invoking
   the open, poll `kicadOpenFileBusy()` until clear (5 min budget — slow loads
   are real; the poll is free). Escape hatch: a visible **non-progress** dialog
   means the load is parked awaiting user input (file-version confirm, remap…)
   — proceed rather than leave the dialog unanswerable under the boot overlay.
   Feature-detected: wasm builds without the probe fall back to the legacy
   title poll unchanged.

3. **Degrade, don't die** — `driveProjectIntoTool` returns the open outcome;
   on `"failed"` the shell skips the whole collab/presence/drift attach
   (board stays viewable, saves still route). The attach block is additionally
   wrapped so a residual trap logs `[collab] attach failed — continuing
   without collab` instead of failing the boot; `SexprVersionError` ("update
   required") still rethrows.

## Layer 4 — entry guards + the regression spec

The shell gate alone leaves the raw embind entries trappable if anything else
calls them mid-load, and is untestable end-to-end (see below). So the collab
snapshot/apply entries themselves early-return while `pcbjam_open::busy()`:
snapshots return the empty delta, applies drop. `kicadTestSetOpenPark(ms)`
(test-only, default off) makes `kicadOpenFile` Asyncify-park for a fixed time
on entry and again after `OpenProjectFiles` returns — model fully loaded, gate
still closed.

`tests/kicad/collab-load-fuzz.spec.ts` uses that window deterministically: it
opens a ~13k-item generated board and hammers all four entries the whole time
`kicadOpenFileBusy()` is true, asserting the gate engages, mid-load snapshots
are EMPTY (an unguarded build returns the full board → deterministic red),
mid-load applies are dropped (probe segment must not move), nothing traps, and
everything works after settle.

**Why the window must be synthetic:** the wasm port's `wxYield`/progress pump
never parks — the only natural in-load parks are thread-pool waits
(`futex_yield`/`nanosleep_yield`), which on a fast idle machine never happen
(the whole open runs synchronously and JS cannot interleave at all). That is
also why the prod trap correlates with slow machines/Firefox. A second,
`PCBJAM_FUZZ_STRESS=1`-gated test in the same spec hunts those natural parks
under spinning-worker CPU starvation; it cannot gate CI (window engagement is
scheduler-dependent) but is the honest reproducer to loop on a loaded box.

## Residuals / notes

- A trap escaping the open leaves the busy count stuck → the JS poll times out
  (5 min) and boots without collab; same end state as before, minus the trap.
- `kicadSetReadOnly` polling during the load is unaffected (leaf flag flip, no
  model walk) — it has always run during parks, like `kicadCollabFiberBusy`.
- The mid-load modal escape accepts the status-quo risk for that rare case:
  parked-at-a-dialog is a stable park point, not a mid-container-append one.
- Unit coverage: `web/standalone/src/wasm/open-flow.test.ts` (settle wait,
  stuck-busy failure, dialog escape incl. progress-dialog exclusion, legacy
  fallback).