defense-in-depth

defense-in-depth

Validate at every layer the value passes through. Fixing the bug at one layer is locally sufficient and globally fragile — the next refactor, code path, mock, or platform edge case will rediscover it. Four-layer validation makes the bug structurally impossible.

When to use

• Bug fix where invalid data caused failure several frames deep.
• New entry point that funnels external input into existing internals.
• Refactor that adds a second caller to a previously single-caller routine.
• Test setup that shortcuts production guards (mocks bypassing entry validation).

Do NOT use when:

• Pure formatting / style change — no data flow, no layers to defend.
• Boundary validation alone is correct (e.g. immutable value object with constructor invariant) — route to laravel-validation.
• The fix belongs at a single architectural seam — adding three more guards is over-engineering. Use the gate function below to stop early.

Procedure: Apply the four-layer pattern

Step 0: Analyze the data flow before adding guards

1. Identify where the bad value originates (test fixture, request body, env var, config).
2. List every function that receives the value before the failure point.
3. Mark which functions are reachable from production paths and which only from tests.

Step 1: Layer 1 — Entry-point validation

Reject obviously invalid input at the API / route / command boundary. In Laravel this is FormRequest rules; in Express a zod-validated middleware; in pure services it is the public method on the service.

public function createProject(string $name, string $workingDirectory): Project
{
    if (trim($workingDirectory) === '') {
        throw new InvalidArgumentException('workingDirectory cannot be empty');
    }
    if (! is_dir($workingDirectory)) {
        throw new InvalidArgumentException("workingDirectory does not exist: {$workingDirectory}");
    }
    if (! is_writable($workingDirectory)) {
        throw new InvalidArgumentException("workingDirectory is not writable: {$workingDirectory}");
    }
    // ... proceed
}