chadfowler.com
Reference implementation for the Phoenix Architecture. Work in progress.
aicoding.leaflet.pub/
ai
coding
crazy
1# Phoenix VCS — System Architecture
2
3## Overview
4
5Phoenix is a causal compiler for intent. It transforms spec documents through a deterministic pipeline into generated code, with full provenance tracking and selective invalidation.
6
7## System Layers
8
9```
10┌─────────────────────────────────────────────────┐
11│ CLI / Bot Interface │
12├─────────────────────────────────────────────────┤
13│ Policy & Evidence Engine │
14├─────────────────────────────────────────────────┤
15│ Regeneration Engine │
16├─────────────────────────────────────────────────┤
17│ Implementation Graph (IU Manager) │
18├─────────────────────────────────────────────────┤
19│ Canonicalization Pipeline │
20├─────────────────────────────────────────────────┤
21│ Spec Ingestion (Clause Extraction) │
22├─────────────────────────────────────────────────┤
23│ Content-Addressed Store │
24│ (Graph DB + Blob Storage) │
25└─────────────────────────────────────────────────┘
26```
27
28## Five Core Graphs
29
301. **Spec Graph** — Clauses extracted from spec documents
312. **Canonical Graph** — Requirements, Constraints, Invariants, Definitions
323. **Implementation Graph** — Implementation Units (IUs) with contracts & boundaries
334. **Evidence Graph** — Tests, analysis results, reviews bound to nodes
345. **Provenance Graph** — All transformation edges connecting the above
35
36## Content Addressing
37
38All nodes use content-based IDs:
39- `clause:{sha256(normalized_text + source_doc_id + section_path)}`
40- `canon:{sha256(canonical_statement + type + linked_clauses)}`
41- `iu:{sha256(kind + contract + boundary_policy)}`
42
43## Directory Structure
44
45```
46.phoenix/ # Phoenix metadata root
47 store/ # Content-addressed store
48 objects/ # All graph nodes (JSON)
49 refs/ # Named references
50 graphs/
51 spec.json # Spec graph index
52 canonical.json # Canonical graph index
53 implementation.json # IU graph index
54 evidence.json # Evidence graph index
55 provenance.json # Provenance edges
56 manifests/
57 generated_manifest.json # Generated file hashes
58 state.json # System state (BOOTSTRAP_COLD, WARMING, STEADY_STATE)
59 config.json # Pipeline configuration
60```
61
62## Build Phases
63
64| Phase | Components | Dependencies |
65|-------|-----------|-------------|
66| A | Clause extraction, clause_semhash | None |
67| B | Canonicalization, warm hashing, classifier | A |
68| C1 | IU module-level, regen, manifest | B |
69| C2 | Boundary validator, UnitBoundaryChange | C1 |
70| D | Evidence, policy, cascade | C2 |
71| E | Shadow pipeline, compaction | D |
72| F | Freeq bots | All |