1# Defense-in-Depth Validation
2 
3## Overview
4 
5When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
6 
7**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
8 
9## Why Multiple Layers
10 
11Single validation: "We fixed the bug"
12Multiple layers: "We made the bug impossible"
13 
14Different layers catch different cases:
15- Entry validation catches most bugs
16- Business logic catches edge cases
17- Environment guards prevent context-specific dangers
18- Debug logging helps when other layers fail
19 
20## The Four Layers
21 
22### Layer 1: Entry Point Validation
23**Purpose:** Reject obviously invalid input at API boundary
24 
25```typescript
26function createProject(name: string, workingDirectory: string) {
27  if (!workingDirectory || workingDirectory.trim() === '') {
28    throw new Error('workingDirectory cannot be empty');
29  }
30  if (!existsSync(workingDirectory)) {
31    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
32  }
33  if (!statSync(workingDirectory).isDirectory()) {
34    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
35  }
36  // ... proceed
37}
38```
39 
40### Layer 2: Business Logic Validation
41**Purpose:** Ensure data makes sense for this operation
42 
43```typescript
44function initializeWorkspace(projectDir: string, sessionId: string) {
45  if (!projectDir) {
46    throw new Error('projectDir required for workspace initialization');
47  }
48  // ... proceed
49}
50```
51 
52### Layer 3: Environment Guards
53**Purpose:** Prevent dangerous operations in specific contexts
54 
55```typescript
56async function gitInit(directory: string) {
57  // In tests, refuse git init outside temp directories
58  if (process.env.NODE_ENV === 'test') {
59    const normalized = normalize(resolve(directory));
60    const tmpDir = normalize(resolve(tmpdir()));
61 
62    if (!normalized.startsWith(tmpDir)) {
63      throw new Error(
64        `Refusing git init outside temp dir during tests: ${directory}`
65      );
66    }
67  }
68  // ... proceed
69}
70```
71 
72### Layer 4: Debug Instrumentation
73**Purpose:** Capture context for forensics
74 
75```typescript
76async function gitInit(directory: string) {
77  const stack = new Error().stack;
78  logger.debug('About to git init', {
79    directory,
80    cwd: process.cwd(),
81    stack,
82  });
83  // ... proceed
84}
85```
86 
87## Applying the Pattern
88 
89When you find a bug:
90 
911. **Trace the data flow** - Where does bad value originate? Where used?
922. **Map all checkpoints** - List every point data passes through
933. **Add validation at each layer** - Entry, business, environment, debug
944. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
95 
96## Example from Session
97 
98Bug: Empty `projectDir` caused `git init` in source code
99 
100**Data flow:**
1011. Test setup → empty string
1022. `Project.create(name, '')`
1033. `WorkspaceManager.createWorkspace('')`
1044. `git init` runs in `process.cwd()`
105 
106**Four layers added:**
107- Layer 1: `Project.create()` validates not empty/exists/writable
108- Layer 2: `WorkspaceManager` validates projectDir not empty
109- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
110- Layer 4: Stack trace logging before git init
111 
112**Result:** All 1847 tests passed, bug impossible to reproduce
113 
114## Key Insight
115 
116All four layers were necessary. During testing, each layer caught bugs the others missed:
117- Different code paths bypassed entry validation
118- Mocks bypassed business logic checks
119- Edge cases on different platforms needed environment guards
120- Debug logging identified structural misuse
121 
122**Don't stop at one validation point.** Add checks at every layer.
123