The Storybook compiler performs multi-layered validation to catch errors before runtime. This chapter documents all validation rules, organized by declaration type, along with the error messages you can expect and how to fix them.
## Validation Layers
Storybook validation happens in four stages:
1.**Lexical**: Tokenization of raw text (invalid characters, malformed literals)
| Variable scope | Quantifier variables only valid within their predicate | Error |
| Enum validity | Enum comparisons must reference defined values | Error |
### Examples
**Type mismatch:**
```storybook
life_arc TypeError {
state checking {
on count == "five" -> done // Error: cannot compare int with string
}
state done {}
}
```
## Use Statement Validation
| Rule | Description | Severity |
|------|-------------|----------|
| Path exists | Imported paths must reference defined modules/items | Error |
| No circular imports | Modules cannot form circular dependency chains | Error |
| Valid identifiers | All path segments must be valid identifiers | Error |
| Grouped import validity | All items in `{}` must exist in the target module | Error |
### Examples
**Missing import:**
```storybook
use schema::nonexistent::Thing; // Error: module 'schema::nonexistent' not found
```
## Cross-File Validation
When resolving across multiple `.sb` files, the compiler performs additional checks:
| Rule | Description | Severity |
|------|-------------|----------|
| All references resolve | Cross-file references must find their targets | Error |
| No naming conflicts | Declarations must not collide across files in the same module | Error |
| Import visibility | Only public declarations can be imported | Error |
## Common Error Patterns
### Missing Definitions
The most common error is referencing something that does not exist:
```storybook
character Martha: Human from Baker {
specialty: sourdough
}
```
If `Human`, `Baker`, or the `sourdough` enum variant are not defined or imported, the compiler will report an error. Fix by adding the appropriate `use` statements:
```storybook
use schema::core_enums::{SkillLevel, Specialty};
use schema::templates::Baker;
use schema::beings::Human;
character Martha: Human from Baker {
specialty: sourdough
}
```
### Circular Dependencies
Circular references are rejected at every level:
- Templates including each other
- Species including each other
- Schedules extending each other
- Modules importing each other
Break cycles by restructuring into a hierarchy or extracting shared parts into a common module.
### Type Mismatches
Storybook has no implicit type coercion. Ensure values match their expected types:
```storybook
// Wrong:
character Bad {
age: "twenty" // Error: expected int, got string
is_ready: 1 // Error: expected bool, got int
}
// Correct:
character Good {
age: 20
is_ready: true
}
```
## Validation Summary
| Declaration | Key Constraints |
|-------------|----------------|
| Character | Unique name, valid species/templates, no circular inheritance |
