# DOL Parser Compatibility Report
Generated: 2025-12-23
## Executive Summary
The biology module files generated by the swarm use **DOL 2.0+ aspirational syntax** that extends beyond the current parser's capabilities. This report details:
1. What syntax the parser **currently supports**
2. What syntax the biology files **actually use**
3. The **gap** between them
4. **Recommendations** for remediation
---
## Current Parser Capabilities
### Supported Declarations
| Gene | `gene Name { statements } exegesis { }` | Supported |
| Trait | `trait Name { statements } exegesis { }` | Supported |
| Constraint | `constraint Name { statements } exegesis { }` | Supported |
| System | `system Name @ Version { statements } exegesis { }` | Supported |
| Evolution | `evolves Name @ Version > ParentVersion { ... } exegesis { }` | Partial |
### Supported Statements (inside declarations)
| Has | `subject has property` | Supported |
| Is | `subject is state` | Supported |
| DerivesFrom | `subject derives from origin` | Supported |
| Requires | `subject requires requirement` | Supported |
| Uses | `uses reference` | Supported |
| Emits | `action emits event` | Supported |
| Matches | `subject matches target` | Supported |
| Never | `subject never action` | Supported |
| Quantified | `each/all phrase` | Supported |
### Supported Lexer Tokens
#### Keywords
- Declaration: `gene`, `trait`, `constraint`, `system`, `evolves`, `exegesis`
- Predicates: `has`, `is`, `derives`, `from`, `requires`, `uses`, `emits`, `matches`, `never`
- Evolution: `adds`, `deprecates`, `removes`, `because`
- Control Flow: `let`, `if`, `else`, `match`, `for`, `while`, `loop`, `break`, `continue`, `return`, `in`, `where`
- Types: `Int8`, `Int16`, `Int32`, `Int64`, `UInt8`, `UInt16`, `UInt32`, `UInt64`, `Float32`, `Float64`, `Bool`, `String`, `Void`
- Functions: `fun`
#### Operators
- Composition: `|>`, `>>`, `:=`, `<|`
- Meta: `'`, `!`, `#`, `?`, `[|`, `|]`
- Arithmetic: `+`, `-`, `*`, `/`, `%`, `^`
- Comparison: `==`, `!=`, `<`, `<=`, `>`, `>=`
- Logical: `&&`, `||`
- Lambda: `->`, `=>`, `|`, `_`
---
## Biology Files Analysis
### Features Used (NOT Currently Supported)
#### 1. Module Declaration
```dol
module biology.types @ 1.0.0
```
**Status**: NOT SUPPORTED
- `module` is not a recognized keyword
- Parser expects `gene`, `trait`, `constraint`, `system`, or `evolves`
#### 2. Import Statement
```dol
use biology.types.{ Vec3, Gradient, Nutrient }
```
**Status**: NOT SUPPORTED
- `use` is not a recognized keyword (only `uses` as a predicate)
- Destructuring imports `{ A, B }` not parsed
#### 3. Visibility Modifier
```dol
pub gene Vec3 { ... }
pub fun from_spore(position: Vec3) -> MyceliumNetwork { ... }
```
**Status**: NOT SUPPORTED
- `pub` is not a recognized keyword
- Visibility modifiers not implemented
#### 4. Generic Type Parameters
```dol
gene Gradient<T> { ... }
uses Transport<Nutrient>
```
**Status**: NOT SUPPORTED
- Generic parameters `<T>` not parsed in declarations
- Generic type arguments parsed only in type expressions, not declaration names
#### 5. Typed Field Declarations with Defaults
```dol
has carbon: Float64 = 70.0
has heritability: Float64 // 0.0 - 1.0
```
**Status**: NOT SUPPORTED
- Parser expects `subject has property` (two identifiers)
- No type annotation syntax (`: Type`)
- No default value syntax (`= value`)
#### 6. Named Constraint Blocks
```dol
constraint stoichiometry {
this.carbon / this.nitrogen >= 6.0
}
```
**Status**: NOT SUPPORTED
- `constraint` is only valid as a top-level declaration
- Not supported as inline blocks inside `gene`/`trait`
#### 7. Function Declarations
```dol
fun magnitude() -> Float64 {
return (this.x * this.x + this.y * this.y).sqrt()
}
```
**Status**: NOT SUPPORTED
- Parser has `parse_function_decl()` but it's not called from `parse_statements()`
- `fun` inside gene/trait bodies not parsed
#### 8. State Declarations
```dol
state nodes: Map<UInt64, MyceliumNode>
state total_biomass: Float64
```
**Status**: NOT SUPPORTED
- `state` is not a recognized keyword
- Only valid statement forms inside `system` are predicates
#### 9. Law Declarations
```dol
law fitness_inheritance {
forall p1: Self, p2: Self. ...
}
```
**Status**: NOT SUPPORTED
- `law` is not a recognized keyword
- `forall` quantifier not implemented
#### 10. Evolution with Timestamp
```dol
evolves Organism > Prokaryote @ 3.5Gya { ... }
```
**Status**: NOT SUPPORTED
- Current syntax: `evolves Name @ Version > ParentVersion`
- Biology uses: `evolves Parent > Child @ Timestamp`
- `3.5Gya` (geological time literal) not tokenized
#### 11. Migration Blocks
```dol
migrate from Organism {
return Prokaryote { ... }
}
```
**Status**: NOT SUPPORTED
- `migrate` is not a recognized keyword
- Block body with expressions not parsed
#### 12. Spread Syntax
```dol
return Trait { ...this, value: inherited }
```
**Status**: NOT SUPPORTED
- `...` spread operator not tokenized
#### 13. Mutable Bindings
```dol
mut next_id = this.next_id
mut output = "..."
```
**Status**: NOT SUPPORTED
- `mut` is not a recognized keyword
#### 14. Logical Keywords
```dol
not this.has_nucleus
this.nucleus is not null
x implies y
```
**Status**: NOT SUPPORTED
- `not` is not a keyword (use `!` instead)
- `implies` is not a keyword
- `null` is not a keyword
---
## Gap Summary
| Missing Keywords | 10+ | High |
| Declaration Syntax | 5 | High |
| Statement Syntax | 6 | High |
| Type Syntax | 3 | Medium |
| Expression Syntax | 4 | Medium |
| Operator Tokens | 2 | Low |
### Missing Keywords (Lexer)
1. `module`
2. `use`
3. `pub`
4. `state`
5. `law`
6. `forall`
7. `implies`
8. `mut`
9. `not`
10. `migrate`
11. `null`
### Missing Declaration Parsing
1. Module declarations
2. Pub visibility modifier
3. Generic type parameters on declarations
4. Typed has statements with defaults
5. Function declarations in bodies
### Missing Statement Parsing
1. Inline constraint blocks
2. State declarations in systems
3. Law declarations in traits
4. Migration blocks in evolution
5. Forall quantifiers
6. Typed field declarations
---
## Recommendations
### Option A: Extend Parser (Full DOL 2.0)
Add support for all features. Estimated changes:
1. **Lexer additions** (~50 lines)
- Add 11 new keywords
- Add `...` spread operator
- Add geological time literals
2. **Parser additions** (~500 lines)
- `parse_module()` - new declaration type
- `parse_use()` - import statements
- Modify `parse_gene/trait/system()` to handle:
- `pub` visibility
- Generic parameters
- Typed `has` statements
- `fun` declarations
- `constraint` blocks
- `state` declarations
- `law` declarations
3. **AST additions** (~100 lines)
- New node types for modules, imports, functions, etc.
**Effort**: ~2-3 days of focused work
### Option B: Simplify Biology Files (Compatibility Mode)
Rewrite biology files to use only currently-supported syntax:
```dol
// Instead of: module biology.types @ 1.0.0
// Use: (no module declaration)
// Instead of: pub gene Vec3 { ... }
gene biology.types.Vec3 {
Vec3 has x
Vec3 has y
Vec3 has z
}
exegesis {
Three-dimensional vector...
}
```
**Limitations**:
- Loses type annotations
- Loses function bodies
- Loses constraints
- Significantly reduced expressiveness
**Effort**: ~1 day, but results in less useful files
### Option C: Phased Approach
Implement in phases, testing biology files at each step:
**Phase 1**: Module + Use + Pub (enables file organization)
**Phase 2**: Typed Has + Defaults (enables proper genes)
**Phase 3**: Fun declarations (enables behavior)
**Phase 4**: Constraint blocks (enables validation)
**Phase 5**: State + Law (enables systems/traits)
**Phase 6**: Evolution extensions (enables speciation)
**Effort**: ~1 week, but allows incremental testing
---
## Current Test Results
```
cargo test --test biology_tests
```
```
running 9 tests
test test_parse_nutrient_gene ... FAILED (module not recognized)
test test_parse_hyphal_trait ... FAILED (module not recognized)
test test_parse_transport_trait ... FAILED (module not recognized)
test test_parse_ecosystem_system ... FAILED (module not recognized)
test test_parse_evolution ... FAILED (module not recognized)
test test_parse_mycelium_network ... FAILED (module not recognized)
test test_nutrient_constraint ... FAILED (constraint block in gene)
test test_evolves_syntax ... FAILED (typed has statement)
test test_ecosystem_constraints ... FAILED (constraint block in system)
test result: FAILED. 0 passed; 9 failed
```
All failures stem from the same root causes documented above.
---
## Conclusion
The biology module represents a **vision** for DOL 2.0+ that the parser hasn't caught up to yet. The swarm generated syntactically rich, scientifically accurate models, but they can't be parsed by the current implementation.
**Recommended path**: Option C (Phased Approach) - implement features incrementally, starting with the most impactful (`module`, `use`, `pub`, typed `has`), and validate against the biology files at each step.