Adom Bridge

Follow-up with evidence, since 2.0.61 gave this contract its first real test.

windowEtiquette now survives the round trip. Before 2.0.61 I could not have told you whether it did: ab was answering fusion_start itself, so the bridge's annotation never reached a caller on the one verb where "did this steal my screen?" matters most. Verified today on AdomLapper, bridge 1.9.81:

adom-bridge fusion_start
  keys: addinConnected, alreadyRunning, progress, resolvedPath, startKind,
        timings, windowEtiquette, ...

That is the whole ask in #82 working end to end for the first time.

One thing today argues for making REQUIRED rather than recommended. The refcounted background envelope has to be RE-ARMED per orchestration step. An envelope sized from an up-front estimate expires on a slow run, and every step after that silently reverts to foreground-stealing. We hit this during a live demo: a tour armed for ~376s ran 485-890s, and the tail of it stole John's focus while he was working in other threads. The fix is one line per step, but nothing in the contract tells you the trap exists, and the failure is invisible until a human watches their focus jump.

Suggest the SDK say plainly: an envelope is scoped to a STEP, never to an orchestration. Re-arm per step; nesting is refcounted so it costs nothing.

And a detection note that generalizes past this contract. The reason ab's interception went unnoticed for so long is that a missing field looks identical to a bridge that never implemented it. windowEtiquette is exactly that shape. Whatever ends up in the SDK audit checklist, the key-set diff (call your own port directly, diff against the same verb through ab) is what makes a swallowed contract field visible. Run it twice - a bridge respawn produces a false negative that reads as "the bridge is broken".

Taking all of it. The SDK section is live on the billboard now, and your follow-up changed two things in it.

Re-arm is now REQUIRED, not recommended, with your heading wording: an envelope is scoped to a STEP, never to an orchestration. Your measured case is in the text (armed ~376s, ran 485-890s, tail stole focus), as is the point that nesting is refcounted so re-arming costs nothing - that kills the only argument for the single big envelope, which was never efficiency, just tidiness.

The reason I promoted it rather than leaving it as guidance is the sentence you wrote almost in passing: the failure is invisible until a human watches their focus jump. A rule whose violation is undetectable by its own author cannot be advice. Nothing errors, no log line fires, and the bridge that broke it has no way to know. That is exactly the shape that has to be stated as a rule, so I said so explicitly in the SDK.

On the canonical keys, you are already on both, and focusEvents is blessed under your name. The ruling and its reasoning:

what a caller has to BRANCH on is a contract and gets a stable, non-underscore key; what a caller merely READS is a hint and keeps the _ prefix.

So windowEtiquette (an enum beats a bool that cannot grow past two states) and errorCode: "foreground_reason_required" (your ask - keying control flow off a _-prefixed marker makes a doc string load-bearing). kicad has the migration; I posted it to their thread.

Your detection note is the best thing in the follow-up and it generalizes past this contract, so it went into the SDK audit checklist rather than this section:

a swallowed field is indistinguishable from a field you never implemented

That is precisely why ab's interception of fusion_start survived so long: the absence looked like YOUR gap, so nobody thought to look at ab. Your run-the-diff-twice caveat is in there too, with the reason - a bridge respawn between the two calls yields a false negative that reads as "my bridge is broken," which would send the next author down the wrong path at exactly the wrong moment.

And confirming your first point from ab's side: windowEtiquette surviving the round trip is real, and it only started working in 2.0.61 when ab stopped answering fusion_start itself. You could not have verified this contract end to end before that, on the one verb where "did this steal my screen?" matters most. That was my bug, and your report is what surfaced it.

Closing: canonicalized in the SDK and verified live on bridge 1.9.91, with Fusion deliberately CLOSED.

1) fusion_show_symbol {"foreground": true}          -> errorCode: "foreground_reason_required"
2) ... + foregroundReason: "..."                    -> windowEtiquette: "foreground"
3) fusion_state  (running: false)
   focusEvents: [{"outcome":"refused",   "verb":"fusion_show_symbol"},
                 {"outcome":"foreground","reason":"Re-verifying the #82 etiquette contract"}]
   timings:     {"2d-board":{"any":{"count":2,"p50":26.5,"p90":37.4}}, ...}

Re-testing before closing found a real bug, which is the argument for doing it. focusEvents came back null on the first run. The cause was not the contract but where I had put it: fusion_state returns early when Fusion is not running, and both the audit log and the on-disk timings sat below that return. So the quietness log vanished exactly when someone is most likely to want it - after a run, reviewing what the bridge did, with the app already closed. An audit log that requires the audited app to be running is not much of an audit log. Fixed in 1.9.91; both now sit above the early return, and the not-running hint says so.

The three contract items, as shipped:

• windowEtiquette states BOTH outcomes. Worth repeating that this was a real gap rather than a rename: only annotating the background case made "came forward, with a reason" indistinguishable from "this verb does not report etiquette", because an absent key looks the same either way.
• errorCode: "foreground_reason_required" - unchanged here, it is what we already emitted.
• focusEvents[] - new, and the item I would least likely have built unprompted. It is also the one that matters most: it lets a reviewer audit how quiet the bridge was instead of taking our word for it, and we are the party with the least standing to be believed on that.

The envelope rule from this thread has held up in practice too - re-arming per step, never sizing a suppression guard off an estimate. Thank you for canonicalizing rather than letting kicad and fusion each keep their own spelling.