0006. Dependency fixes go upstream first

• Status: accepted
• Date: 2026-07-21

Context

Two defects in dependencies stood between this executor and correct behaviour. isolated-vm’s promise bridge resolved a host promise without a microtask checkpoint, so an awaiting continuation inside the isolate parked until some unrelated callback happened to run a checkpoint. capnweb’s transport refused to serialize a raw ArrayBuffer, breaking binary bodies across the process boundary.

Both were bugs in the dependency, not in the way the dependency was used, and each had an answer available on this side of the boundary. For the stall it was a keepalive timer that kept the loop busy enough to hide it. That answer leaves the real cause in place and charges rent on it forever. For either defect, vendoring a corrected copy forks the dependency permanently and moves its maintenance here.

Decision

Every needed dependency fix is contributed upstream. Finding the root cause in the dependency’s own source is part of the work, and the fix is written to be mergeable there. Until a release carries the fix, a local patch bridges. That patch contains exactly the upstream commit applied to the upstream tag, byte for byte their code, with no invention alongside it. When a release ships the fix, the patchedDependencies entry and the patch file are deleted, and no other file in the repository changes. Dependency releases carrying a merged fix are tracked the same way a security advisory is: each retires a patch.

Consequences

Patches are workspace-local. Consumers installing the published package receive the vanilla dependency, so a patch can never be the mechanism that makes published behaviour correct. Publishing while a fix is still unreleased upstream requires a different carrier.

The recorded fallback for that case is a scoped fork: the upstream tag plus the one merged upstream commit, released under this project’s scope, with the executor depending on the scoped package. When the original releases, the dependency swaps back through a version bump and no code change. But the fork exists only if publishing arrives before the upstream release does.

Patches that touch native code force a build from source, because shipped prebuilds would bypass the patched sources. So the daemon image is committed to carrying a build toolchain, and cold CI caches compile the addon. Regression tests for a patched defect live here as timing pins with proven red and green states. A patch that silently stops applying fails the suite. It does not degrade quietly.