# The SBIR Binary Format

SBIR (Storybook Intermediate Representation) is the compiled binary format produced by the Storybook compiler. It transforms human-readable `.sb` files into an optimized, machine-consumable format for simulation runtimes.

## Compilation Pipeline

```
.sb files → Lexer → Parser → AST → Resolver → SBIR Binary
```

1. **Lexer**: Tokenizes raw text into tokens
2. **Parser**: Builds an Abstract Syntax Tree (AST) from tokens
3. **Resolver**: Validates, resolves cross-references, merges templates, and produces SBIR

## What SBIR Contains

SBIR represents the fully resolved state of a Storybook project:

- **Characters**: All fields resolved (species + templates merged, overrides applied)
- **Behaviors**: Behavior trees with all subtree references inlined
- **Life Arcs**: State machines with validated transitions
- **Schedules**: Time blocks with resolved action references
- **Relationships**: Participants with resolved entity references
- **Institutions**: Fully resolved field sets
- **Locations**: Fully resolved field sets
- **Species**: Fully resolved inheritance chains
- **Enums**: Complete variant lists

## Resolution Process

### Template Merging

When a character uses templates, SBIR contains the fully merged result:

**Source:**
```storybook
species Human { lifespan: 70, speed: 1.0 }
template Warrior { speed: 1.5, strength: 10 }

character Conan: Human from Warrior {
    strength: 20
}
```

**In SBIR, Conan's fields are:**
- `lifespan: 70` (from Human)
- `speed: 1.5` (Warrior overrides Human)
- `strength: 20` (Conan overrides Warrior)

### Cross-File Reference Resolution

SBIR resolves all `use` statements and qualified paths. A relationship referencing `Martha` in a different file is resolved to the concrete character definition.

### Validation

Before producing SBIR, the resolver validates all constraints documented in [Validation Rules](../reference/19-validation.md):
- All references resolve to defined declarations
- No circular dependencies
- Type consistency
- Domain constraints (bond ranges, schedule validity)

## Design Goals

**Compact**: SBIR strips comments, whitespace, and redundant structure.

**Self-contained**: No external references -- everything is resolved and inlined.

**Fast to load**: Simulation runtimes can load SBIR without re-parsing or re-resolving.

**Validated**: If SBIR was produced, the source was valid. Runtimes do not need to re-validate.

## Usage

SBIR is consumed by simulation runtimes that drive character behavior, schedule execution, life arc transitions, and relationship queries. The specific binary format is implementation-defined and may evolve between versions.

For the current SBIR specification, see the [SBIR v0.2.0 Spec](../SBIR-v0.2.0-SPEC.md).

## Cross-References

- [Language Overview](../reference/09-overview.md) - Compilation model
- [Validation Rules](../reference/19-validation.md) - What is validated before SBIR production
- [Integration Guide](./22-integration.md) - How runtimes consume SBIR