Seam check — prove a boundary from the other side

Understanding the Seam Check

The concept of a "seam check" comes from the seam-check skill, which is all about testing the boundary between two systems. This isn't about testing the components themselves, but the join where they interact. The primary goal is to ensure that the boundary is proven from the far side, meaning the external or receiving end, so that we don't just trust our own systems saying everything is fine. This approach is crucial in avoiding situations where a "green" status board belies an underlying issue.

The Four Rules of Seam Check

The seam check skill outlines four essential rules. First, expectations should be declared in configuration files, not buried in code. This ensures that machines can continuously validate them. Second, the test must occur against the real production environment, not a mocked version, as assumptions embedded in test fixtures won't catch the real-world problems. Third, the result must be read from the far side, meaning the external system, not our own logs or status codes. If this isn't possible, the result should be marked as UNKNOWN. Lastly, any absence of expected data or responses should be treated as a loud alert—stale or missing data should trigger a red status or a paging alert.

Refusal as the First Line of Defense

A core principle is that probes should target systems we control. The code should be designed to refuse operations that don't resolve to our owned destinations. The logic is simple: anything that gets queued can potentially be sent before it can be cleaned up, and once an action is visible to its owner, it's too late. The refusal logic should be driven by the destination, not the caller's intent, and ideally, the artifact should be written in a state that a worker won't process, providing a fail-safe that doesn't rely on timing.

The Seam Check Procedure

The procedure begins by naming the seam as from → to and categorizing it into one of four core functions: reach, notify, act, or prove. If it doesn't fit, it's considered width and allowed to be marked UNKNOWN. Next, identify the far side—something you can read that wasn't written by your system, like an external inbox or a third-party record. Also, determine the negative control—what the check should refuse. This step ensures that endpoints aren't indiscriminately accepting inputs, which would invalidate the seam check.

Write the logic for the seam check separately from the system logic, focusing on the judge, classifier, or allowlist test, and ensure it's well unit-tested. The first production run is often more revealing of your own system's assumptions than external issues, so expect to refine the process.

Finally, integrate the outcome into existing monitoring systems, such as a Telegram page for alerts, and implement a dead-man's switch to catch when the check itself fails to run. This check should be registered with a clear line of visibility to ensure it doesn't become another silent failure.