Dependencies and research

Few dependencies here are replaceable. An isolate engine, an RPC transport, and the upstream package this executor stands in for: each one is load-bearing, and none can be swapped in an afternoon. So a dependency here is a standing decision, not a line in a manifest. Most of the work a dependency costs is spent before anything gets installed.

Study a dependency from its repository

Read a dependency from its real repository: the sources, the tests, the history. Built dist output and rolled-up typings will tell you what a function accepts. But only the repository tells you who owns a behaviour, which layer decided it, and whether anyone decided it on purpose.

• Read the API at the released tag matching the installed version, never at the clone’s HEAD. Behaviour on main may be months away from a release, and building on it means building on something no consumer has.
• Ground an integration decision in the upstream layer that owns the behaviour, read before deciding. Decisions taken from the package surface guess at ownership and call the guess a design.
• Check whether the problem already has an upstream answer before designing one here. An open pull request, or a merged commit waiting on a release, changes what the right fix is.

Copying is not importing

Byte-level copying from another project, in place of importing it, needs explicit approval before a single line lands. A copy forks upstream the moment it is made: the original keeps moving, the copy does not, and no tool anywhere reports the divergence.

Sometimes a duty falls to this executor because upstream cannot deliver its implementation to this runtime. That duty gets a module of its own here, written from the requirement and never transcribed, and Design states the rule in full. The differential suite in Testing then proves compatibility end to end, and no copy could ever have supported a claim that strong.

Patch upstream first, carry the patch locally

When a dependency needs a fix, the fix goes upstream. A local patch bridges the wait. That patch is exactly upstream’s commit, not a local reinterpretation of it, so the patched tree and the eventual release behave the same and the upgrade is uneventful.

• Record patches through pnpm’s patchedDependencies, keyed by the exact version they apply to. Version bumps then force somebody to look at the patch, where an unkeyed one would be silently dropped or misapplied.
• Retire a patch the moment the upstream release carrying the fix lands. A patch that outlives its release is a fork of upstream that nobody decided to keep.
• Resolve the consumer gap before publishing. Local patches apply to this repository’s installs and never reach consumers of the published packages. So a fix that consumers depend on ships as a released dependency version, not as a patch file, and Decision 0006 names what carries it in place of a patch.

Currency and advisories

Dependencies stay current. An old tree accumulates advisories faster than it accumulates reasons to stay old.

• Scope an advisory override to the majors actually present in the tree, and say in a comment which dependent has to move before the override can drop. Unscoped overrides quietly rewrite versions nobody audited.
• Treat the minimumReleaseAge cooldown as supply-chain protection and not as friction. Freshly published versions are exactly the shape a compromised release takes. But wanting the newest number is never a reason to bypass the wait.
• Prefer removing a dependency over patching it, whenever the code it carries is smaller than the integration it demands.

Declaring a range, never a pin

@cloudflare/codemode is a peer dependency. Its range is declared with both ends stated.

• Never pin the integration target as a direct dependency of a published package. Pinning turns a compatible upgrade on the consumer’s side into a conflict they did not ask for.
• Prove the declared range, never assert it. The compatibility suite installs the newest supported line under the upstream package name and every older line under a versioned npm alias. Each line gets its own run in the version matrix, so the range in peerDependencies and the range under test are the same set.
• Widen or narrow the range and the matrix in one change. A range that outruns its matrix is an untested promise, and because the promise is written in semantic versioning terms, a consumer’s resolver will act on it without asking anyone first.