Phoenix VCS — System Architecture#

Overview#

Phoenix is a causal compiler for intent. It transforms spec documents through a deterministic pipeline into generated code, with full provenance tracking and selective invalidation.

System Layers#

┌─────────────────────────────────────────────────┐
│                   CLI / Bot Interface            │
├─────────────────────────────────────────────────┤
│              Policy & Evidence Engine            │
├─────────────────────────────────────────────────┤
│             Regeneration Engine                  │
├─────────────────────────────────────────────────┤
│        Implementation Graph (IU Manager)        │
├─────────────────────────────────────────────────┤
│        Canonicalization Pipeline                 │
├─────────────────────────────────────────────────┤
│     Spec Ingestion (Clause Extraction)          │
├─────────────────────────────────────────────────┤
│          Content-Addressed Store                │
│         (Graph DB + Blob Storage)               │
└─────────────────────────────────────────────────┘

Five Core Graphs#

Spec Graph — Clauses extracted from spec documents
Canonical Graph — Requirements, Constraints, Invariants, Definitions
Implementation Graph — Implementation Units (IUs) with contracts & boundaries
Evidence Graph — Tests, analysis results, reviews bound to nodes
Provenance Graph — All transformation edges connecting the above

Content Addressing#

All nodes use content-based IDs:

clause:{sha256(normalized_text + source_doc_id + section_path)}
canon:{sha256(canonical_statement + type + linked_clauses)}
iu:{sha256(kind + contract + boundary_policy)}

Directory Structure#

.phoenix/                    # Phoenix metadata root
  store/                     # Content-addressed store
    objects/                 # All graph nodes (JSON)
    refs/                    # Named references
  graphs/
    spec.json                # Spec graph index
    canonical.json           # Canonical graph index
    implementation.json      # IU graph index
    evidence.json            # Evidence graph index
    provenance.json          # Provenance edges
  manifests/
    generated_manifest.json  # Generated file hashes
  state.json                 # System state (BOOTSTRAP_COLD, WARMING, STEADY_STATE)
  config.json                # Pipeline configuration

Build Phases#

Phase	Components	Dependencies
A	Clause extraction, clause_semhash	None
B	Canonicalization, warm hashing, classifier	A
C1	IU module-level, regen, manifest	B
C2	Boundary validator, UnitBoundaryChange	C1
D	Evidence, policy, cascade	C2
E	Shadow pipeline, compaction	D
F	Freeq bots	All