chadfowler.com
Reference implementation for the Phoenix Architecture. Work in progress.
aicoding.leaflet.pub/
ai
coding
crazy
1# Phase C1 — Implementation Units, Regeneration & Manifest
2
3## Overview
4
5Phase C1 introduces Implementation Units (IUs) — stable compilation boundaries that
6map canonical requirements to generated code. The regeneration engine produces code
7artifacts and tracks them in a generated manifest for drift detection.
8
9## Components
10
11### 1. Implementation Unit Model (`src/models/iu.ts`)
12
13```typescript
14interface ImplementationUnit {
15 iu_id: string; // content-addressed
16 kind: 'module' | 'function';
17 name: string; // human-readable label
18 risk_tier: 'low' | 'medium' | 'high' | 'critical';
19 contract: IUContract; // inputs, outputs, invariants
20 source_canon_ids: string[]; // which canonical nodes this implements
21 dependencies: string[]; // other iu_ids this depends on
22 boundary_policy: BoundaryPolicy; // what it's allowed to touch
23 evidence_policy: EvidencePolicy; // what proof is required
24 output_files: string[]; // generated file paths
25}
26```
27
28### 2. IU Planner (`src/iu-planner.ts`)
29
30Maps canonical nodes → IU proposals. Groups related requirements into
31module-level IUs based on:
32- Shared tags/terms
33- Same source clause
34- Linked canonical nodes
35
36### 3. Regeneration Engine (`src/regen.ts`)
37
38Generates code stubs for each IU. Records:
39- model_id (or "stub-generator/1.0" for v1)
40- promptpack hash
41- toolchain version
42
43Outputs:
44- Generated source files (TypeScript stubs)
45- Per-file content hashes in the manifest
46
47### 4. Generated Manifest (`src/manifest.ts`)
48
49Tracks every generated file:
50
51```typescript
52interface GeneratedManifest {
53 iu_manifests: Record<string, IUManifest>;
54 generated_at: string;
55}
56
57interface IUManifest {
58 iu_id: string;
59 files: Record<string, FileManifestEntry>;
60 regen_metadata: RegenMetadata;
61}
62
63interface FileManifestEntry {
64 path: string;
65 content_hash: string;
66 size: number;
67}
68```
69
70### 5. Drift Detector (`src/drift.ts`)
71
72Compares working tree files against the generated manifest:
73
74- **CLEAN**: file matches manifest hash
75- **DRIFTED**: file differs, no waiver
76- **WAIVED**: file differs, waiver exists
77- **MISSING**: manifest entry but no file
78- **UNTRACKED**: file exists but not in manifest
79
80## Data Flow
81
82```
83CanonicalNodes (Phase B)
84 → IUPlanner.plan() → ImplementationUnit[]
85 → RegenEngine.generate() → generated files + RegenMetadata
86 → Manifest.record() → generated_manifest.json
87 → DriftDetector.check() → DriftReport
88```