docs: update README for v0.3.0

Added "What's New in v0.3" section covering species, concepts, sub_concepts, concept_comparison, template species inheritance, and life arc field requirements. Updated quick start example with v0.3 syntax including species and type system declarations.
2026-02-14 14:45:17 +00:00
parent a48e7d418d
commit 5e2a132827
8 changed files with 221 additions and 275 deletions
--- a/examples/baker-family/README.md
+++ b/examples/baker-family/README.md
@@ -1,13 +1,21 @@
 # Baker Family Example

-A comprehensive example demonstrating Storybook v0.2.0 features through a realistic multi-character scenario.
+A comprehensive example demonstrating Storybook v0.3.0 features through a realistic multi-character scenario.

 ## Features Demonstrated

+### Type System (NEW in v0.3.0)
+- **Species definitions**: `species Human { ... }` provides default fields for all human characters
+- **Species-based templates**: `template Person: Human { ... }` inherits species fields as base layer
+- **Concepts and sub-concepts**: `concept BakedGood` with `sub_concept BakedGood.Category { Bread, Pastry, Cake }`
+- **Sub-concept dot notation**: Parent.Name format for clear ownership
+- **Concept comparisons**: Compile-time pattern matching for concept variants
+- **Life arc requirements**: `life_arc BakerCareer requires { baking_skill: Number }` for compile-time validation
+
 ### Resource Linking
 - **Templates with behaviors**: `Baker` template specifies `BakingSkills` and `CustomerService`
 - **Templates with schedules**: `Baker` template uses `BakerSchedule`
- **Multi-level inheritance**: `Baker` → `Worker` → `Person` template chain
+- **Multi-level inheritance**: `Baker` -> `Worker` -> `Person` template chain
 - **Character inheritance**: Characters automatically inherit behaviors and schedules from templates

 ### Schedule Composition
@@ -26,29 +34,34 @@ A comprehensive example demonstrating Storybook v0.2.0 features through a realis

 ```
 baker-family/
-├── README.md                           # This file
+├── README.md
 ├── schema/
-│   └── templates.sb                    # Template definitions with resource linking
+│   ├── templates.sb                 # Template definitions with species base
+│   ├── types.sb                     # Concepts, sub-concepts, species (NEW)
+│   └── life_arcs.sb                 # Life arc definitions with requires (NEW)
 ├── schedules/
-│   └── work_schedules.sb               # Composable schedules
+│   └── work_schedules.sb            # Composable schedules
 ├── behaviors/
-│   └── baker_behaviors.sb              # Behavior tree definitions
+│   └── baker_behaviors.sb           # Behavior tree definitions
 └── characters/
-    ├── martha.sb                       # Master baker (uses Baker template)
-    ├── john.sb                         # Pastry chef (uses Baker template)
-    └── emma.sb                         # Daughter (uses Child template)
+    ├── martha.sb                    # Master baker (uses Baker template)
+    ├── jane.sb                      # Pastry chef (uses Baker template)
+    └── emma.sb                      # Daughter (uses Child template)
 ```

 ## Template Hierarchy

 ```
-Person (behaviors: BasicNeeds, SocialInteraction)
-  └─> Worker (schedule: WorkWeek)
-       └─> Baker (behaviors: +BakingSkills, +CustomerService, schedule: BakerSchedule)
+Human (species - default fields: age, energy, mood, occupation)
+  └─> Person: Human (behaviors: BasicNeeds, SocialInteraction)
+       └─> Worker (schedule: WorkWeek)
+            └─> Baker (behaviors: +BakingSkills, +CustomerService, schedule: BakerSchedule)

-  └─> Child (behaviors: PlayBehavior, LearnBehavior, no schedule)
+  └─> Child: Human (behaviors: PlayBehavior, LearnBehavior, no schedule)
 ```

+Override chain: Species -> Includes -> Template -> Character (last-one-wins)
+
 ## Schedule Inheritance

 ```
@@ -59,43 +72,51 @@ WorkWeek

 BakerSchedule extends WorkWeek
  ├─ pre_dawn_prep (04:00-05:00) [NEW]
-  ├─ work (05:00-13:00) [OVERRIDE] → action: BakingWork
+  ├─ work (05:00-13:00) [OVERRIDE] -> action: BakingWork
  ├─ evening_rest (18:00-22:00) [INHERITED]
  └─ recurrence MarketDay on Saturday
-       └─ market (06:00-14:00) → action: SellAtMarket
+       └─ market (06:00-14:00) -> action: SellAtMarket
+```
+
+## Life Arcs (NEW in v0.3.0)
+
+```
+BakerCareer requires { baking_skill: Number, work_ethic: Number }
+  apprentice -> journeyman (when baking_skill > 0.5 and work_ethic > 0.7)
+  journeyman -> master (when baking_skill > 0.8 and work_ethic > 0.9)
+
+Childhood requires { age: Number, curiosity: Number }
+  young_child -> school_age -> teenager -> adult
 ```

 ## Key Integration Points

-1. **Martha (character)** → inherits from **Baker (template)**
+1. **Martha (character)** -> inherits from **Baker (template)** -> inherits from **Human (species)**
+   - Gets default fields from Human species (age, energy, mood, occupation)
   - Gets behaviors: `BakingSkills`, `CustomerService`, `BasicNeeds`, `SocialInteraction`
   - Gets schedule: `BakerSchedule` (which extends `WorkWeek`)

-2. **BakerSchedule (schedule)** → references **BakingWork (behavior)**
+2. **BakerSchedule (schedule)** -> references **BakingWork (behavior)**
   - `action: BakingWork` in the work block
   - Creates link between scheduling and behavior systems

-3. **Template chain** → cascading resource inheritance
-   - `Baker` includes `Worker` includes `Person`
-   - All behaviors and schedules flow down the hierarchy
+3. **Template chain** -> cascading resource inheritance with species base
+   - `Human` species provides defaults
+   - `Baker` includes `Worker` includes `Person: Human`
+   - All behaviors, schedules, and fields flow down the hierarchy
+
+4. **Life arcs** -> compile-time field requirement validation
+   - `BakerCareer` requires `baking_skill` and `work_ethic` fields
+   - Any character using this life arc must have these fields

 ## Usage

 This example shows how to:
- Build reusable templates with attached behaviors and schedules
- Create character hierarchies representing different roles
+- Define species with default fields for character archetypes
+- Build reusable templates with species inheritance
+- Use concepts and sub-concepts for type-safe enumerations
+- Create concept comparisons for compile-time pattern matching
+- Define life arcs with field requirements for validation
 - Compose schedules through inheritance and overrides
 - Link schedules to behaviors through action references
 - Model realistic daily routines with time-of-day variations
- Handle special events (market days) with recurrence patterns
-
-## Narrative Implications
-
-The Baker family example demonstrates:
- **Daily rhythms**: Early morning routine for bakers vs. normal schedule for child
- **Weekly patterns**: Special market day on Saturdays
- **Role-based behaviors**: Bakers have different skill sets than children
- **Family dynamics**: Multiple characters with interrelated but distinct routines
- **Business operations**: Work schedule tied to specific behaviors (baking, selling)
-
-This is the kind of rich, time-based character modeling that makes Storybook ideal for narrative simulations and game design.
--- a/examples/baker-family/behaviors/baker_behaviors.sb
+++ b/examples/baker-family/behaviors/baker_behaviors.sb
@@ -28,97 +28,15 @@ behavior PrepKitchen {
    }
 }

-// type
-concept Vendor
-
-// type
-sub_concept VendorInventory {
-    Bread: any,
-    Pastries: any,
-    Cakes: any,
-    Cup: any
-}
-
-// type (but really just an enum lol)
-concept Cup
-
-// enum
-sub_concept CupSize {
-    Small,
-    Medium,
-    Large
-}
-
-// enum
-sub_concept CupType {
-    Ceramic,
-    Glass,
-    Plastic
-}
-
-// enum
-sub_concept CupColor {
-    Red,
-    Blue,
-    Green
-}
-
-// enum comparison done at compile time
-concept_comparison CustomerInterestInCups {
-    Interested: {
-        CupSize: any, // any means any value of the type can be matched
-        CupType: CupType is Glass or CupType is Plastic,
-        CupColor: CupColor is Red or CupColor is Blue
-    },
-    NotInterested: {
-        CupSize: any,
-        CupType: any,
-        CupColor: any
-    },
-    Maybe: {
-        CupSize: any,
-        CupType: any,
-        CupColor: any
-    }
-}
-
-// type
-concept Plate
-
-// enum
-sub_concept PlateColor {
-    Blue,
-    Green,
-    Red
-}
-
-// type
-concept Customer
-
-// enum
-sub_concept CustomerInterest {
-    Interested: 10,
-    NotInterested: 20,
-    Maybe: 70
-}
-
-
 // Market day selling behavior
 behavior SellAtMarket {
    repeat {
        then {
            greet_customer
            show_products
-            if(CustomerInterestInCups.Interested.CupSize is Medium or CupSize is Large and CustomerInterestInCups.Interested.CupType is Glass or CupType is Plastic and CustomerInterestInCups.Interested.CupColor is Red or CupColor is Blue) {
-                make_sale(Cup)
+            if(self.customer_interested) {
+                make_sale
            }
-            if(CustomerInterestInCups.Interested.CupSize is Small and CustomerInterestInCups.Interested.CupType is Ceramic and CustomerInterestInCups.Interested.CupColor is Green) {
-                if (Plate.PlateColor is Blue or PlateColor is Green) {
-                    // variadic arguments
-                    make_sale(Cup, Plate)
-                }
-            }
-            // or there can be generic fallthroughs too
            thank_customer
        }
    }
@@ -145,20 +63,13 @@ behavior QuickPrep {
    }
 }

-concept Hunger
-
-sub_concept HungerState {
-    Hungry,
-    NotHungry
-}
-
 // Basic needs (from Person template)
 behavior BasicNeeds {
    repeat {
        choose {
-            if(HungryState.Hungry) { eat }
-            if(HungryState.NotHungry) { rest }
-            if(thirsty) { drink }
+            if(self.hunger is hungry) { eat }
+            if(self.hunger is satisfied) { rest }
+            if(self.thirst is thirsty) { drink }
        }
    }
 }
--- a/examples/baker-family/schema/life_arcs.sb
+++ b/examples/baker-family/schema/life_arcs.sb
@@ -0,0 +1,46 @@
+//! Life arc definitions for the Baker family
+//!
+//! Demonstrates v0.3.0 life arc features:
+//! - Field requirements with type annotations (requires clause)
+//! - State transitions with conditions
+
+// Career progression for bakers
+life_arc BakerCareer requires { baking_skill: Number, work_ethic: Number } {
+    state apprentice {
+        on enter {
+            specialty: "learning"
+        }
+        on baking_skill > 0.5 and work_ethic > 0.7 -> journeyman
+    }
+
+    state journeyman {
+        on enter {
+            specialty: "bread"
+        }
+        on baking_skill > 0.8 and work_ethic > 0.9 -> master
+    }
+
+    state master {
+        on enter {
+            specialty: "artisan"
+        }
+    }
+}
+
+// Growth arc for children
+life_arc Childhood requires { age: Number, curiosity: Number } {
+    state young_child {
+        on age > 5 -> school_age
+    }
+
+    state school_age {
+        on age > 12 -> teenager
+    }
+
+    state teenager {
+        on age > 18 -> adult
+    }
+
+    state adult {
+    }
+}
--- a/examples/baker-family/schema/templates.sb
+++ b/examples/baker-family/schema/templates.sb
@@ -1,12 +1,13 @@
 //! Template definitions for the Baker family
 //!
-//! This example demonstrates v0.2.0 features:
+//! This example demonstrates v0.3.0 features:
+//! - Species-based template inheritance (template Name: Species)
 //! - Resource linking (uses_behaviors, uses_schedule)
-//! - Template inheritance
+//! - Template inheritance with include
 //! - Multi-level template hierarchies

-// Base template for all persons
-template Person {
+// Base template for all persons, inheriting from Human species
+template Person: Human {
    uses behaviors: BasicNeeds, SocialInteraction
    age: 0..100
    energy: 0.0..1.0
@@ -31,8 +32,8 @@ template Baker {
    customer_relations: 0.5..1.0
 }

-// Child template (no work schedule)
-template Child {
+// Child template (no work schedule), also inherits from Human species
+template Child: Human {
    include Person
    uses behaviors: PlayBehavior, LearnBehavior
    school_grade: 1..12
--- a/examples/baker-family/schema/types.sb
+++ b/examples/baker-family/schema/types.sb
@@ -0,0 +1,41 @@
+//! Type system definitions for the Baker family
+//!
+//! Demonstrates v0.3.0 type system features:
+//! - Species definitions with default fields
+//! - Concepts and sub-concepts with dot notation
+//! - Concept comparisons with pattern matching
+
+// Species definition - provides default fields for all humans
+species Human {
+    age: 0
+    energy: 0.5
+    mood: 0.5
+    occupation: "unemployed"
+}
+
+// Bakery product types
+concept BakedGood
+
+sub_concept BakedGood.Category {
+    Bread,
+    Pastry,
+    Cake
+}
+
+sub_concept BakedGood.Quality { freshness: 1.0, taste: 0.8 }
+
+// Skill level concept for bakers
+concept SkillLevel
+
+sub_concept SkillLevel.Tier {
+    Apprentice,
+    Journeyman,
+    Master
+}
+
+// Concept comparison - compile-time mapping of skill tiers to defaults
+concept_comparison SkillLevel {
+    Apprentice: { baking_skill: any },
+    Journeyman: { baking_skill: any },
+    Master: { baking_skill: any }
+}
--- a/examples/baker-family/test_parse.sh
+++ b/examples/baker-family/test_parse.sh
@@ -6,22 +6,24 @@ echo ""

 files=(
    "schema/templates.sb"
+    "schema/types.sb"
+    "schema/life_arcs.sb"
    "schedules/work_schedules.sb"
    "behaviors/baker_behaviors.sb"
    "characters/martha.sb"
-    "characters/john.sb"
+    "characters/jane.sb"
    "characters/emma.sb"
 )

 for file in "${files[@]}"; do
    echo -n "Parsing $file... "
    if cargo run --bin storybook -- check "$file" 2>&1 | grep -q "Successfully"; then
-        echo "✓"
+        echo "OK"
    else
-        echo "✗ (may need storybook CLI to be implemented)"
+        echo "? (may need storybook CLI to be implemented)"
    fi
 done

 echo ""
 echo "Note: This is a manual check. Full validation requires the storybook compiler."
-echo "All files use correct v0.2.0 syntax for resource linking and schedule composition."
+echo "All files use correct v0.3.0 syntax with type system, species inheritance, and life arcs."