# SBIR Changelog

All notable changes to the Storybook Intermediate Representation format.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

> **Note:** As of v0.3.0, value type names have been renamed: Int→Number,
> Float→Decimal, String→Text, Bool→Boolean. Historical entries below use the
> original terminology from their respective versions.

---

## [0.3.2] - 2026-02-23

### Changed

**Keyword Rename:**
- The `concept_comparison` keyword has been renamed to `definition`
  - Old: `concept_comparison SkillLevel { ... }`
  - New: `definition SkillLevel { ... }`
  - No binary format changes required - this is a source-level rename only
  - The Rust AST type `ConceptComparisonDecl` is renamed to `DefinitionDecl`

---

## [0.2.0] - 2026-02-13

### Added

**Resource Linking System:**
- `BehaviorLink` struct for conditional behavior attachment
  - Priority system (Low, Normal, High, Critical)
  - Conditional activation via expressions
  - Default fallback behavior
- `ScheduleLink` struct for conditional schedule attachment
  - First-match conditional selection
  - Default fallback schedule
- Extended `Character` with `behavior_links` and `schedule_links` vectors
- Extended `Institution` with `behavior_links` and `schedule_links` vectors

**Year-Long Schedule System:**
- `Schedule.parent_schedule_id` for inheritance
- `Schedule.patterns` for temporal patterns
- `SchedulePattern` enum with three variants:
  - `DayPattern` - day-specific blocks
  - `SeasonPattern` - seasonal blocks
  - `RecurrencePattern` - recurring events
- `RecurrenceSpec` with variants:
  - Every N days
  - Weekly on specific days
  - Monthly on day N
  - Annually on month/day
- Pattern-based schedule composition and merging
- User-definable calendar enums (DayOfWeek, Season, Month)

**Behavior Tree Enhancements:**
- Optional `label` field on Selector and Sequence nodes (for debugging)
- Parameterized decorators:
  - `DecoratorRepeatN(u32)` - repeat N times
  - `DecoratorRepeatRange(u32, u32)` - repeat min..max times
  - `DecoratorRetry(u32)` - retry up to N times
  - `DecoratorTimeout(u64)` - timeout after milliseconds
  - `DecoratorCooldown(u64)` - cooldown period
  - `DecoratorIf(Expression)` - conditional if
  - `DecoratorSucceedAlways` - always succeed
  - `DecoratorFailAlways` - always fail
- Keyword syntax support (choose, then, if, when, repeat, etc.)

### Changed

**Breaking:**
- `ScheduleBlock.name` is now required (was `Option<String>`)
- `ScheduleBlock.start` and `end` changed from `Time` struct to `u16` (minutes since midnight)
- `ScheduleBlock.activity: String` removed, replaced with `behavior_ref: Option<Vec<String>>`
- Binary format version updated from 0x0001 to 0x0002
- Character and Institution sections have different binary layout (added link vectors)
- Schedule section completely redesigned

**Non-breaking:**
- Behavior tree Selector/Sequence nodes extended (backward compatible if label is None)

### Removed

- `ScheduleBlock.activity` field (replaced by `behavior_ref`)

### Deprecated

- None (first formal release)

### Fixed

- None (first formal release)

### Security

- None

---

## [0.1.0] - Implicit (Pre-Release)

Initial format (inferred from codebase, never formally specified).

### Included

- Basic entity storage:
  - Characters with species and field maps
  - Templates with includes
  - Species definitions
  - Enums
- Simple schedules:
  - Time blocks with activity strings
  - Optional block names
- Behavior trees:
  - Symbolic syntax (?, >, !, @, ~)
  - Basic decorators (repeat with * sigil)
  - Action nodes with parameters
  - Conditions and subtree references
- Relationships with participants
- Locations
- Life arcs (state machines)
- Institutions

### Known Limitations

- No resource linking (behaviors/schedules hard-coded per entity)
- No schedule patterns (single 24-hour template only)
- No parameterized decorators
- No named behavior tree nodes
- No formal specification document

---

## Migration Notes

### From 0.1.0 to 0.2.0

**Required Actions:**
1. Recompile source files OR
2. Use `storybook-migrate` tool for binary migration

**Key Changes:**
- All schedules must have named blocks
- Activity strings converted to behavior references
- Characters/Institutions gain empty link vectors (if not specified)
- Time values converted to minutes since midnight

**See:** `/docs/SBIR-MIGRATION-GUIDE.md` for detailed instructions.

---

## Version Numbering

SBIR follows semantic versioning:
- **Major** (x.0.0): Incompatible changes requiring migration
- **Minor** (0.x.0): Backward-compatible additions
- **Patch** (0.0.x): Bug fixes, no format changes

**Current:** v0.2.0 (first formal release)
**Next Minor:** v0.3.0 (planned features TBD)
**Next Major:** v1.0.0 (when format stabilizes)

---

## Unreleased

_Track upcoming changes here_

### Planned for v0.3.0

- [ ] Compressed string table option
- [ ] Symbol index for faster lookups
- [ ] Metadata section for tooling info

### Under Consideration

- [ ] Module system for multi-file worlds
- [ ] Asset references (audio, images)
- [ ] Localization support

---

[0.2.0]: https://github.com/your-org/storybook/releases/tag/sbir-v0.2.0
[0.1.0]: (implicit, no release)