runtime-dependency-boundaries

Runtime dependency boundaries

Apply this rule when adding or moving dependency calls into startup, request handling, discovery, or recurring orchestration in the server, adapters, or runner. A dependency includes a runtime API, filesystem, database, subprocess, or remote service.

Account for the work at the call site

Establish what the dependency actually does: whether it blocks shared execution, how often it runs, what its cost grows with, and how it fails or stops. Reading a small result does not imply a cheap operation. Use implementation, documentation, or measurement as evidence when the behavior is not established.

Match repeated work to how often its underlying facts can change. Account for calls inside loops and repeated requests. Keep unrelated work responsive when the dependency is slow or unavailable. If using a timeout or cancellation, verify that it can take effect while the operation is running and account for work that continues after the caller stops waiting.

Test the assumption that could invalidate the design

Identify the consequential assumption introduced by the change and choose evidence that could disprove it. Check whether mocks remove the behavior being relied upon, such as timing, contention, cancellation, persistence, or external side effects. Where they do, exercise that boundary with a representative real dependency or a controlled fault that preserves the relevant behavior.

Verify the affected contract, including unrelated work that must remain responsive, rather than only the returned value. Keep coverage proportional to the changed behavior; an exhaustive environment matrix is unnecessary. Record the assumption, evidence, and remaining limits in the PR's verification section.

Examples and limits

• A configuration getter that reads a network filesystem needs evidence about slow or unavailable storage and the effect on other work using that process.
• A remote permission check moved inside a search-result loop needs evidence about call count and latency as the result set grows. Any reuse must preserve authorization scope and freshness.
• Reading an already-loaded map or changing a pure value transformation does not require dependency-failure testing unless the change introduces a consequential cost or behavior assumption. Cosmetic edits do not trigger it.