chadfowler.com
Reference implementation for the Phoenix Architecture. Work in progress.
aicoding.leaflet.pub/
ai
coding
crazy
1# Phase C2 — Boundary Validator & UnitBoundaryChange
2
3## Overview
4
5Phase C2 enforces architectural boundaries declared by each IU. The boundary
6validator (architectural linter) extracts the dependency graph from generated
7code and checks it against the IU's boundary policy. Violations produce
8diagnostics that feed into `phoenix status`.
9
10## Components
11
12### 1. Boundary Policy Model (in `src/models/iu.ts`)
13
14```typescript
15interface BoundaryPolicy {
16 code: {
17 allowed_ius: string[]; // IU IDs this may import from
18 allowed_packages: string[]; // npm packages allowed
19 forbidden_ius: string[]; // explicitly blocked IU IDs
20 forbidden_packages: string[]; // explicitly blocked packages
21 forbidden_paths: string[]; // glob patterns (e.g. "src/internal/**")
22 };
23 side_channels: {
24 databases: string[]; // allowed DB names / connection strings
25 queues: string[];
26 caches: string[];
27 config: string[]; // env vars / config keys
28 external_apis: string[]; // URLs / service names
29 files: string[]; // filesystem paths
30 };
31}
32```
33
34### 2. Dependency Extractor (`src/dep-extractor.ts`)
35
36Parses generated TypeScript files and extracts:
37- `import` / `require` statements → package or relative path
38- Known side-channel patterns (env var reads, DB connections, fetch calls)
39
40Returns a `DependencyGraph` for validation.
41
42### 3. Boundary Validator (`src/boundary-validator.ts`)
43
44Validates extracted dependencies against the IU's boundary policy.
45
46Produces `BoundaryDiagnostic[]`:
47- `dependency_violation`: imports something forbidden or not in allowlist
48- `side_channel_violation`: uses undeclared side channel
49
50Each diagnostic has severity (error | warning) controlled by the IU's
51enforcement config.
52
53### 4. UnitBoundaryChange Detector
54
55When an IU's boundary policy changes, emits a `UnitBoundaryChange` event
56that triggers re-validation of the IU and all dependents.
57
58## Diagnostic Model
59
60```typescript
61interface BoundaryDiagnostic {
62 severity: 'error' | 'warning';
63 category: 'dependency_violation' | 'side_channel_violation';
64 iu_id: string;
65 subject: string; // the offending import / channel
66 message: string;
67 source_file?: string;
68 source_line?: number;
69}
70```
71
72## Data Flow
73
74```
75Generated code (Phase C1)
76 → DepExtractor.extract() → DependencyGraph
77 → BoundaryValidator.validate(graph, policy) → BoundaryDiagnostic[]
78 → StatusEngine.merge() → phoenix status
79```