GGL Architecture — Clockwork Horologist View

Section 01

Overview

GGL is an evolution-native programming language — an agent-emittable intermediate representation where types carry their own version history as a first-class property of the type system. Types know what they used to be, how to migrate between versions, and whether consumers on older versions are still compatible.

Core Innovation: Where other languages treat versioning as an external concern (semver, protobuf field numbers, Avro schemas), GGL makes version lineage, migration paths, and compatibility classification intrinsic to the type itself.

20K+

Lines Rust

420+

Tests

28

Experiments

9

Crates

5

MCP Tools

2

ADRs

Section 02

Core Pipeline

Source code flows through a classical compiler pipeline, from lexing through parsing to a typed registry, then branches into either execution (producing JSON kernel output) or code generation (emitting Rust or Go source).

Data Flow — Source to Output

graph LR
    SRC[".ggl Source"]
    LEX["Lexer"]
    TOK["Tokens"]
    PAR["Parser"]
    AST["AST"]
    BRG["Bridge"]
    REG["TypeRegistry"]
    EXE["Executor"]
    KER["KernelOutput"]
    JSON["JSON"]

    SRC --> LEX --> TOK --> PAR --> AST --> BRG --> REG --> EXE --> KER --> JSON

    style SRC fill:#5A4230,stroke:#C5A55A,color:#F0E8D8
    style LEX fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style TOK fill:#D4B96E,stroke:#A68A3E,color:#1A140E
    style PAR fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style AST fill:#D4B96E,stroke:#A68A3E,color:#1A140E
    style BRG fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style REG fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style EXE fill:#A82035,stroke:#C83848,color:#F0E8D8
    style KER fill:#A82035,stroke:#C83848,color:#F0E8D8
    style JSON fill:#5A4230,stroke:#C5A55A,color:#F0E8D8

Parallel Codegen Path

graph LR
    REG2["TypeRegistry"]
    PLAN["CodegenPlan"]
    RUST["Rust Source"]
    GO["Go Source"]

    REG2 --> PLAN
    PLAN --> RUST
    PLAN --> GO

    style REG2 fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style PLAN fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style RUST fill:#C48B6C,stroke:#A06A4C,color:#1A140E
    style GO fill:#C48B6C,stroke:#A06A4C,color:#1A140E

Section 03

Parser & Lexer

The front-end uses a hand-written recursive-descent parser operating on a stream of tokens produced by the lexer. Both are LL(1) — no backtracking, no ambiguity.

Parser Architecture

graph TD
    SRC["Source Text"]
    LEX["Lexer
38 keywords"]
    TOKS["Token Stream"]
    PAR["Parser
Recursive Descent, LL(1)"]
    AST["AST"]

    subgraph AST_NODES ["8 TopLevelItem Variants"]
        TD1["TypeDecl"]
        TD2["MigrateDecl"]
        TD3["FunctionDecl"]
        TD4["ContractDecl"]
        TD5["ImportDecl"]
        TD6["QueryDecl"]
        TD7["TestDecl"]
        TD8["ExperimentDecl"]
    end

    SRC --> LEX --> TOKS --> PAR --> AST
    AST --> AST_NODES

    style SRC fill:#5A4230,stroke:#C5A55A,color:#F0E8D8
    style LEX fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style TOKS fill:#D4B96E,stroke:#A68A3E,color:#1A140E
    style PAR fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style AST fill:#D4B96E,stroke:#A68A3E,color:#1A140E
    style TD1 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD2 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD3 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD4 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD5 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD6 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD7 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TD8 fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8

Token Categories

38 reserved keywords (type, migrate, contract, ...)
Literals: string, int, float, bool
Symbols: braces, arrows, operators
Identifiers and version literals (@1, @2)

AST Node Types

TypeDecl — versioned type definitions
MigrateDecl — migration blocks
FunctionDecl — named functions
ContractDecl — compatibility contracts
QueryDecl, TestDecl, ImportDecl, ExperimentDecl

Expression Types

22 Expr variants including literals, binary/unary ops, field access, function calls, match expressions, record/enum/list constructors, if/let, and pipe operators.

105

Tests

~1,950

Lines

Section 04

Type System Kernel

The kernel is the heart of GGL. It maintains a registry of type families, each containing multiple versions, migration paths, structural hashes (SHA3-512), and lineage information. The bridge translates the AST into registry entries.

Kernel Module Breakdown

graph TD
    subgraph BRIDGE ["bridge.rs (3,800 lines)"]
        B1["AST to Registry
Translation"]
    end

    subgraph REGISTRY ["registry.rs (2,400 lines)"]
        R1["TypeFamily"]
        R2["TypeVersion"]
        R3["BTreeMap versions"]
        R4["BTreeMap migrations"]
        R5["structural_hashes
SHA3-512"]
        R6["lineage_hash"]
        R1 --> R2
        R1 --> R3
        R1 --> R4
        R1 --> R5
        R1 --> R6
    end

    subgraph EXEC ["executor.rs (2,380 lines)"]
        E1["Execute queries
and tests"]
    end

    subgraph EVAL ["eval.rs (2,880 lines)"]
        EV1["Expression
evaluator"]
    end

    B1 --> R1
    R1 --> E1
    E1 --> EV1

    style B1 fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style R1 fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style R2 fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style R3 fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style R4 fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style R5 fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style R6 fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style E1 fill:#A82035,stroke:#C83848,color:#F0E8D8
    style EV1 fill:#A82035,stroke:#C83848,color:#F0E8D8

registry.rs 2,400 lines

TypeFamily and TypeVersion management. Stores version trees, structural hashes, migration edges, and lineage hashes.

bridge.rs 3,800 lines

Translates parsed AST nodes into typed registry entries. Resolves references, checks structural validity, computes hashes.

executor.rs 2,380 lines

Runs queries, tests, and experiments against the registry. Orchestrates migration and evaluation.

eval.rs 2,880 lines

Expression evaluator with 22 Expr variants, builtins, pattern matching, and Result/Option support.

migration.rs 2,000 lines

Migration path finder (BFS), auto-migration engine, and chain composition.

compatibility.rs 1,470 lines

Compatibility classification: isomorphic, lossless, lossy, partial. Structural diff and field-level analysis.

validation.rs 1,320 lines

Schema validation, constraint checking, and well-formedness rules for types and migrations.

solver.rs 1,830 lines

Version constraint solver. Monotone lattice fixpoint algorithm. O(V×E) per module.

version.rs 860 lines

Version algebra: ordering, ranges, union/intersection, resource lattice operations.

289+

Tests

~18K

Lines (kernel)

Section 05

Migration Engine

Migrations are first-class: GGL finds paths between versions via BFS, classifies each step, and applies transforms automatically or via user-defined migration bodies. Nested fields are auto-migrated recursively.

Migration Pipeline

flowchart TD
    IN["Input Value"]
    FIND["Find Migration Path
(BFS)"]
    STEP["For Each Step"]
    CHECK{"Auto or
Manual?"}
    AUTO["Auto: copy identity fields,
apply defaults, drop, rename"]
    MANUAL["Manual: eval body AST
with self = value"]
    NEST["Post-step:
auto-migrate nested fields"]
    VALID["Validate schema"]
    NEXT{"More
steps?"}
    OUT["Output Value"]

    IN --> FIND --> STEP --> CHECK
    CHECK -- Auto --> AUTO --> NEST
    CHECK -- Manual --> MANUAL --> NEST
    NEST --> VALID --> NEXT
    NEXT -- Yes --> STEP
    NEXT -- No --> OUT

    style IN fill:#5A4230,stroke:#C5A55A,color:#F0E8D8
    style FIND fill:#A82035,stroke:#C83848,color:#F0E8D8
    style STEP fill:#A82035,stroke:#C83848,color:#F0E8D8
    style CHECK fill:#C83848,stroke:#A82035,color:#F0E8D8
    style AUTO fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style MANUAL fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style NEST fill:#A82035,stroke:#C83848,color:#F0E8D8
    style VALID fill:#3A7A4A,stroke:#3A7A4A,color:#F0E8D8
    style NEXT fill:#C83848,stroke:#A82035,color:#F0E8D8
    style OUT fill:#5A4230,stroke:#C5A55A,color:#F0E8D8

Classification	Direction	Data Loss	Description
Isomorphic	Forward + Reverse	None	Lossless in both directions. Field renames, reordering.
Lossless	Forward only	None	No information lost going forward. Adding fields with defaults.
Lossy	Forward only	Some	Information discarded. Dropping fields, narrowing types.
Partial	Forward only	Possible failure	Migration may fail for some values. Validation-dependent.

Chain Composition: Migration chains compose their classifications conservatively — the chain is only as strong as its weakest link. An isomorphic + lossy chain is classified as lossy overall.

Section 06

Version Solver & Contracts

The solver resolves version constraints across a dependency graph using a monotone lattice fixpoint algorithm. Contracts declare compatibility requirements that the solver must satisfy.

VersionResource Algebra

graph LR
    BOT["Bottom
(no version)"]
    ANY["Any
(all versions)"]
    EX["Exact(v)"]
    RNG["Range(lo, hi)"]
    UNI["Union"]
    INT["Intersect"]

    ANY --> EX
    ANY --> RNG
    EX --> INT
    RNG --> INT
    EX --> UNI
    RNG --> UNI
    UNI --> INT
    INT --> BOT

    style BOT fill:#5A4230,stroke:#C5A55A,color:#F0E8D8
    style ANY fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style EX fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style RNG fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style UNI fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8
    style INT fill:#3A4E78,stroke:#2A3A5C,color:#F0E8D8

Constraint Types

Exact — pin to a specific version
Intersect — narrow to overlap
Union — accept any of several ranges
SubResource — must be subset
Extract — project from composite
Migrate — must have migration path

Algorithm

Monotone lattice fixpoint iteration. Each round propagates constraints until no variable changes. Worst case O(V×E) per module. Terminates because the lattice is finite and monotone-ascending.

Contract Enforcement

Find the type family
Resolve version constraints
Verify migration path exists
Check classification meets requirement
Verify structural hash compatibility

Section 07

Expression Evaluator

The evaluator in eval.rs handles all GGL expressions at runtime, from simple literals through pattern matching, function calls, and collection operations.

Evaluation Dispatch

graph TD
    EVAL["eval_expr()"]

    subgraph SIMPLE ["Literals & Ops"]
        LIT["Literals
int, float, string, bool"]
        BIN["BinOp / UnaryOp"]
        FIELD["FieldAccess"]
    end

    subgraph CONSTRUCT ["Constructors"]
        REC["RecordLit"]
        ENUM["EnumLit"]
        LIST["ListLit"]
    end

    subgraph CONTROL ["Control Flow"]
        CALL["Call
(builtins + user fns)"]
        MATCH["Match / If / Let"]
        PIPE["Pipe Operator"]
    end

    EVAL --> LIT
    EVAL --> BIN
    EVAL --> FIELD
    EVAL --> REC
    EVAL --> ENUM
    EVAL --> LIST
    EVAL --> CALL
    EVAL --> MATCH
    EVAL --> PIPE

    style EVAL fill:#A82035,stroke:#C83848,color:#F0E8D8
    style LIT fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style BIN fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style FIELD fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style REC fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style ENUM fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style LIST fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style CALL fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style MATCH fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style PIPE fill:#C48B6C,stroke:#D4A68A,color:#1A140E

Builtin Functions

String: split, concat, join, to_string
Collection: len, first, get, fold, map, filter
Option: some, none, unwrap
Result: ok, err, is_ok, is_err
Utility: validate_email, version, wrap

Result<T, E> Support

First-class ok(val) and err(msg) constructors. Pattern matching on results with match. Propagation through migration chains.

Collection Operations

fold, map, and filter accept function callbacks (lambdas or named fns). List operations are lazy-friendly but currently eager-evaluated.

Section 08

Code Generation

GGL has a 3-layer codegen architecture: a language-neutral IR layer, plus backend crates that emit Rust and Go source code. A build-time integration crate enables compile-time generation from .ggl files.

12

IR Variants

4

Crates

2

Target Languages

Codegen Architecture

graph LR
    TR["TypeRegistry"]

    subgraph IR_LAYER ["codegen-core (IR)"]
        PLAN["CodegenPlan
types + migrations + chains"]
        CGEN_IR["CodegenIR
12 variants"]
        BACKEND["CodegenBackend trait"]
    end

    subgraph RUST_OUT ["codegen-rust"]
        RUST_GEN["Rust Generator"]
        RUST_SRC["Rust Source
#[derive(Serialize, ...)]
migrate_v1_to_v2()"]
    end

    subgraph GO_OUT ["codegen-go"]
        GO_GEN["Go Generator"]
        GO_SRC["Go Source
json tags
UnmarshalAndMigrate()"]
    end

    BUILD["ggl-build
build.rs integration"]

    TR --> PLAN
    PLAN --> CGEN_IR
    CGEN_IR --> BACKEND
    BACKEND --> RUST_GEN
    BACKEND --> GO_GEN
    RUST_GEN --> RUST_SRC
    GO_GEN --> GO_SRC
    BUILD --> RUST_GEN

    style TR fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style PLAN fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style CGEN_IR fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style BACKEND fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style RUST_GEN fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style RUST_SRC fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style GO_GEN fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style GO_SRC fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style BUILD fill:#A82035,stroke:#C83848,color:#F0E8D8

codegen-core

Language-neutral IR layer. CodegenIR has 12 variants: Literal, FieldAccess, BinOp, UnaryOp, RecordConstruct, ListConstruct, Builtin, IfElse, LetBinding, Variable, MatchExpr, EnumConstruct. Outputs a CodegenPlan (types + migrations + chains) consumed by backends via the CodegenBackend trait.

codegen-rust

Generates Rust structs with #[derive(Serialize, Deserialize, Clone, Debug)]. Produces migration functions migrate_{type}_v{from}_to_v{to}(), chain dispatchers, and version-detecting deserializers.

codegen-go

Generates Go structs with json:"..." tags. Produces migration functions and UnmarshalAndMigrate auto-migrating unmarshalers that detect the version and run the full chain.

ggl-build

Cargo build.rs integration. Call build_ggl(input_dir, out_dir) to scan for .ggl files and generate Rust source at compile time. Consumes codegen-rust internally.

Section 09

MCP Server & Agent Interface

The MCP server (proto/mcp-server) exposes 5 tools over the stdio protocol, enabling AI agents to parse, typecheck, migrate, and generate code from .ggl files without touching the compiler directly. Also serves ggl://cheatsheet as an MCP resource.

MCP Tool Architecture

graph TD
    AGENT["AI Agent"]

    subgraph MCP_PROTO ["MCP Protocol (stdio)"]
        SERVER["GGL MCP Server"]
    end

    subgraph TOOLS ["5 Tools"]
        EVAL_T["ggl_evaluate
parse + typecheck"]
        CHECK_T["ggl_check_compatibility
diff-based compat"]
        MIGRATE_T["ggl_migrate_value
JSON migration"]
        RUST_T["ggl_codegen_rust
Rust source"]
        GO_T["ggl_codegen_go
Go source"]
    end

    subgraph ENGINE ["Compiler Engine"]
        TYREG["TypeRegistry"]
        CPLAN["CodegenPlan"]
    end

    OUTPUT["JSON / Source Output"]

    AGENT --> SERVER
    SERVER --> EVAL_T
    SERVER --> CHECK_T
    SERVER --> MIGRATE_T
    SERVER --> RUST_T
    SERVER --> GO_T
    EVAL_T --> TYREG
    CHECK_T --> TYREG
    MIGRATE_T --> TYREG
    RUST_T --> CPLAN
    GO_T --> CPLAN
    TYREG --> OUTPUT
    CPLAN --> OUTPUT

    style AGENT fill:#2848A0,stroke:#3A60C0,color:#F0E8D8
    style SERVER fill:#2848A0,stroke:#3A60C0,color:#F0E8D8
    style EVAL_T fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style CHECK_T fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style MIGRATE_T fill:#A82035,stroke:#C83848,color:#F0E8D8
    style RUST_T fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style GO_T fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style TYREG fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style CPLAN fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style OUTPUT fill:#C5A55A,stroke:#A68A3E,color:#1A140E

Agent Workflow: Agent emits .ggl → ggl_evaluate (fix errors) → ggl_check_compatibility → ggl_migrate_value → ggl_codegen_rust / ggl_codegen_go.

ggl_evaluate

Parse + typecheck a .ggl source string. Returns full KernelOutput as JSON: types, versions, migrations, constraints, errors. Primary feedback loop for agents.

ggl_check_compatibility

Diff-based compatibility check. Accepts old and new .ggl source, reports breaking changes, missing migrations, and version conflicts.

ggl_migrate_value

Execute a migration on a concrete JSON value. Accepts a type name, source version, target version, and a JSON payload. Returns the migrated value or error.

ggl_codegen_rust

Generate compilable Rust source from .ggl input. Returns a string of Rust code with structs, derives, migration functions, and chain dispatchers.

ggl_codegen_go

Generate compilable Go source from .ggl input. Returns a string of Go code with structs, json tags, migration functions, and auto-migrating unmarshalers.

Dependencies: ggl-typechecker, ggl-codegen-core, ggl-codegen-rust, ggl-codegen-go.

Section 10

SQL Bridge

Bidirectional SQL ↔ GGL conversion (proof of concept, 16 tests). Generates PostgreSQL DDL from versioned types and can reverse-engineer .ggl source from existing CREATE TABLE statements.

16

Tests

2

Directions

4

Type Mappings

SQL Bridge Data Flow

graph LR
    subgraph GGL_SIDE [".ggl Types"]
        TYPES["Versioned Types
v1, v2, v3..."]
        FAMILY["Type Family
grouped versions"]
    end

    subgraph BRIDGE ["SQL Bridge"]
        TO_SQL["ggl_to_sql
diff consecutive versions"]
        TO_GGL["sql_to_ggl
parse CREATE TABLE"]
    end

    subgraph SQL_SIDE ["PostgreSQL DDL"]
        CREATE["CREATE TABLE
(from v1)"]
        ALTER["ALTER TABLE
ADD/DROP/ALTER COLUMN
(from v2+)"]
    end

    TYPES --> FAMILY
    FAMILY --> TO_SQL
    TO_SQL --> CREATE
    TO_SQL --> ALTER
    CREATE --> TO_GGL
    TO_GGL --> TYPES

    style TYPES fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style FAMILY fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style TO_SQL fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style TO_GGL fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style CREATE fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style ALTER fill:#C5A55A,stroke:#A68A3E,color:#1A140E

ggl_to_sql

Groups types by family, diffs consecutive versions. Generates CREATE TABLE for v1, then ALTER TABLE ADD/DROP/ALTER COLUMN for v2+. Table naming uses naive pluralization (User → users).

sql_to_ggl

Parses CREATE TABLE statements and generates .ggl source with @v1 version blocks. Reverse-engineers a schema into evolution-native types.

Type Mapping

GGL	PostgreSQL
`String`	`TEXT`
`Int`	`INTEGER`
`Bool`	`BOOLEAN`
`Float`	`DOUBLE PRECISION`

Section 11

The GGL Loop

The ggl-loop is a 5-mode autonomous development workflow that drives the entire project. Each session starts by assessing project state, then selects a mode based on a decision table.

Mode Decision Table:

State	Mode
Open decision issues	Resolve
Ready issues with prompts	Execute
Open issues, none ready	Plan
No open issues	Discover
Test failures	Fix

Session Mode Selection

flowchart TD
    START["Session Start"]
    ASSESS["Assess State"]
    DEC{"Decisions
open?"}
    READY{"Ready
issues?"}
    OPEN{"Open
issues?"}
    TESTS{"Tests
passing?"}

    RESOLVE["Resolve Mode
Frame → Propose → Attack → Decide"]
    EXECUTE["Execute Mode
Wave Runner"]
    PLAN["Plan Mode
Prioritize + Prompt"]
    DISCOVER["Discover Mode
IDEAS.md → Experiment"]
    FIX["Fix Mode
Diagnose + Repair"]

    START --> ASSESS
    ASSESS --> DEC
    DEC -->|Yes| RESOLVE
    DEC -->|No| READY
    READY -->|Yes| EXECUTE
    READY -->|No| OPEN
    OPEN -->|Yes| PLAN
    OPEN -->|No| TESTS
    TESTS -->|Fail| FIX
    TESTS -->|Pass| DISCOVER

    style START fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style ASSESS fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style DEC fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style READY fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style OPEN fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style TESTS fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style RESOLVE fill:#A82035,stroke:#C83848,color:#F0E8D8
    style EXECUTE fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style PLAN fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style DISCOVER fill:#2848A0,stroke:#3A60C0,color:#F0E8D8
    style FIX fill:#C5A55A,stroke:#A68A3E,color:#1A140E

Execute Wave Detail

graph TD
    SNAP["Snapshot
save state"]
    DISPATCH["Dispatch
Sonnet agent"]
    IMPL["Implementation
commits + tests"]
    GATE{"Evaluation
Gate"}
    QUICK["Quick Gate
Sonnet tests + Opus diff"]
    FULL["Full Gate
4 parallel agents"]
    KEEP["Keep Changes"]
    REVERT["Discard + Revert"]
    NEXT["Next Wave
or Closeout"]

    SNAP --> DISPATCH
    DISPATCH --> IMPL
    IMPL --> GATE
    GATE -->|Quick| QUICK
    GATE -->|Full| FULL
    QUICK --> KEEP
    QUICK --> REVERT
    FULL --> KEEP
    FULL --> REVERT
    KEEP --> NEXT
    REVERT --> NEXT

    style SNAP fill:#C5A55A,stroke:#A68A3E,color:#1A140E
    style DISPATCH fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style IMPL fill:#C48B6C,stroke:#D4A68A,color:#1A140E
    style GATE fill:#3D2B1A,stroke:#C5A55A,color:#F0E8D8
    style QUICK fill:#2A3A5C,stroke:#3A4E78,color:#F0E8D8
    style FULL fill:#2848A0,stroke:#3A60C0,color:#F0E8D8
    style KEEP fill:#3A7A4A,stroke:#2A6A3A,color:#F0E8D8
    style REVERT fill:#A82035,stroke:#C83848,color:#F0E8D8
    style NEXT fill:#C5A55A,stroke:#A68A3E,color:#1A140E

Resolve Mode

Frame the decision → Propose (2-3 agents) → Attack (Opus + Codex adversarial) → Decide → Record ADR → Collapse spec. Gate: must change code or tests.

Execute Mode

Snapshot state → Dispatch Sonnet implementation agent → Evaluation gate (Quick: Sonnet tests + Opus diff review; Full: 4 parallel agents) → Keep or Discard → Next wave.

Discover Mode

Check IDEAS.md → Update experiments → Adversarial review (Opus + Codex) → Frontier experiment → Plan + Execute follow-up.

Agent Roles

Opus: Design decisions, adversarial review
Sonnet: Implementation, code generation
Haiku: Exploration, lightweight scanning
Codex: Different-family adversarial review

Section 12

Reference

Milestone Timeline

Session	Milestone
1	Inception — language concept, first parser
2–3	Core type system, version blocks, field tracking
4–5	Migration engine, chain resolution, SHA3 hashing
6–8	Constraint solver, contract enforcement, evaluator
9–10	Codegen IR, Rust backend, Go backend
11–12	MCP server, agent tooling, cheatsheet resource
13–15	SQL bridge, enum support, pattern matching
16–18	GGL Loop, autonomous workflow, Wave Runner
19–20	Result<T,E>, collection ops, builtins expansion
21–22	Productization complete — 420+ tests, 28 experiments

Acronym Grid

GGL

Generational Graph Language

IR

Intermediate Representation

AST

Abstract Syntax Tree

BFS

Breadth-First Search

CAS

Content-Addressable Storage

ADR

Architecture Decision Record

MCP

Model Context Protocol

SHA3

Secure Hash Algorithm 3

DDL

Data Definition Language

FK

Foreign Key

LL(1)

Left-to-right, Leftmost derivation, 1 lookahead

PoC

Proof of Concept

EBNF

Extended Backus-Naur Form

MVCC

Multi-Version Concurrency Control

Key Files

File	Purpose
`spec/ggl-spec.md`	Language specification
`spec/ggl-kernel.md`	Kernel semantics & evaluation rules
`CLAUDE.md`	Agent instructions & project context
`HUMAN.md`	Human developer onboarding
`design/process.md`	GGL Loop process definition
`proto/mcp-server/`	MCP server crate (5 tools + resource)
`proto/codegen-core/`	Language-neutral codegen IR
`proto/codegen-rust/`	Rust code generator backend
`proto/codegen-go/`	Go code generator backend

Crate Dependencies

Crate	Dependencies
`ggl-parser`	None (leaf crate)
`ggl-typechecker`	`ggl-parser`
`ggl-migration`	`ggl-parser`, `ggl-typechecker`
`ggl-codegen-core`	`ggl-typechecker`
`ggl-codegen-rust`	`ggl-codegen-core`
`ggl-codegen-go`	`ggl-codegen-core`
`ggl-build`	`ggl-codegen-rust`, `ggl-typechecker`
`ggl-sql`	`ggl-typechecker`
`ggl-mcp-server`	`ggl-typechecker`, `ggl-codegen-core`, `ggl-codegen-rust`, `ggl-codegen-go`