# Relationships - Storybook Language Guide
Comprehensive documentation for the Storybook narrative simulation language

# Relationships

Relationships define connections between characters, institutions, and other entities. They capture social bonds, power dynamics, emotional ties, and interactive patterns. Relationships can be symmetric (friendship) or asymmetric (parent-child), and support bidirectional perspectives where each participant has different fields.

## What is a Relationship?

A relationship connects two or more participants and describes:

- Participants: The entities involved (characters, institutions)
- Roles: Optional labels (parent, employer, spouse)
- Shared fields: Properties of the relationship itself (bond strength, duration)
- Perspective fields: How each participant views the relationship (`self`/`other` blocks)

    Relationship: ParentChild
    ├─ Participant: Martha (as parent)
    │   ├─ self: { responsibility: 1.0, protective: 0.9 }
    │   └─ other: { dependent: 0.8 }
    ├─ Participant: Tommy (as child)
    └─ Shared: { bond: 0.9, years_together: 8 }

## Syntax

    <relationship-decl> ::= "relationship" <identifier> <body>

    <body> ::= "{" <participant>+ <field>* "}"

    <participant> ::= <qualified-path> <role-clause>? <perspective-blocks>?

    <role-clause> ::= "as" <identifier>

    <perspective-blocks> ::= "self" "{" <field>* "}" "other" "{" <field>* "}"
                           | "self" "{" <field>* "}"
                           | "other" "{" <field>* "}"

    <field> ::= <identifier> ":" <value>

## Basic Relationships

### Simple Two-Party Relationship

    relationship Friendship {
        Martha
        Gregory
        bond: 0.8
        years_known: 15
    }

Semantics:

- Two participants: Martha and Gregory
- Shared field: `bond` (strength of friendship)
- Shared field: `years_known` (duration)

### Multi-Party Relationship

    relationship Family {
        Martha
        David
        Tommy
        Elena

        household: "Baker Residence"
        family_bond: 0.95
    }

Relationships can have any number of participants.

## Roles

Roles label a participant’s function in the relationship.

### Syntax

    ParticipantName as role_name

### Examples

    relationship Marriage {
        Martha as spouse
        David as spouse

        bond: 0.9
        anniversary: "2015-06-20"
    }

    relationship ParentChild {
        Martha as parent
        Tommy as child

        bond: 0.95
        guardianship: true
    }

    relationship EmployerEmployee {
        Martha as employer
        Elena as employee

        workplace: "Martha's Bakery"
        salary: 45000
    }

### Role Semantics

- Labels: Roles are descriptive labels, not types
- Multiple roles: Same person can have different roles in different relationships
- Optional: Roles are optional—participants can be unnamed
- Flexibility: No predefined role vocabulary—use what makes sense

## Perspective Fields (Self/Other Blocks)

Perspective fields specify how each participant views the relationship. They enable asymmetric, bidirectional relationships.

### Syntax

    ParticipantName as role self {
        // Fields describing this participant's perspective
    } other {
        // Fields describing how this participant views others
    }

### Self Block

The `self` block contains fields about how the participant experiences the relationship:

    relationship ParentChild {
        Martha as parent self {
            responsibility: 1.0
            protective: 0.9
            anxiety_level: 0.6
        }
        Tommy as child
    }

Martha’s perspective:

- `responsibility`: She feels 100% responsible
- `protective`: She’s highly protective (90%)
- `anxiety_level`: Moderate anxiety about parenting

### Other Block

The `other` block contains fields about how the participant views the other participants:

    relationship ParentChild {
        Martha as parent self {
            responsibility: 1.0
        } other {
            dependent: 0.8      // She sees Tommy as 80% dependent
            mature_for_age: 0.7  // She thinks he's fairly mature
        }
        Tommy as child
    }

### Both Blocks

    relationship EmployerEmployee {
        Martha as employer self {
            authority: 0.9
            stress: 0.6
        } other {
            respect: 0.8
            trust: 0.85
        }
        Elena as employee
    }

Martha’s perspective:

- Self: She has high authority (90%), moderate stress (60%)
- Other: She respects Elena (80%), trusts her (85%)

### Asymmetric Relationships

Different participants can have different perspective fields:

    relationship TeacherStudent {
        Gandalf as teacher self {
            patience: 0.8
            wisdom_to_impart: 1.0
        } other {
            potential: 0.9
            ready_to_learn: 0.6
        }

        Frodo as student self {
            eager_to_learn: 0.7
            overwhelmed: 0.5
        } other {
            admiration: 0.95
            intimidated: 0.4
        }

        bond: 0.85
    }

Gandalf’s view:

- He’s patient (80%), has much wisdom to share
- Sees Frodo as having high potential but only moderately ready

Frodo’s view:

- He’s eager but overwhelmed
- Deeply admires Gandalf, slightly intimidated

## Shared Fields

Fields declared at the relationship level (not in `self`/`other` blocks) are shared among all participants.

    relationship Friendship {
        Martha
        Gregory

        bond: 0.8           // Shared: mutual bond strength
        years_known: 15     // Shared: how long they've known each other
        shared_routines: 3  // Shared: number of daily routines
    }

Common shared fields:

- `bond`: Relationship strength (0.0 to 1.0)
- `years_known`: Duration of relationship
- `trust`: Mutual trust level
- `commitment`: Commitment to the relationship
- `compatibility`: How well they get along

## Prose Blocks

Relationships can include prose blocks for narrative context.

    relationship MarthaAndGregory {
        Martha {
            role: shopkeeper
            values_loyalty: 0.9

            ---perspective
            Martha appreciates Gregory's unwavering loyalty. He has
            been buying her sourdough loaf every morning for fifteen
            years. Their brief daily exchanges about the weather and
            local gossip are a comforting routine.
            ---
        }

        Gregory {
            role: regular_customer
            always_orders: "sourdough_loaf"

            ---perspective
            Gregory considers Martha's bakery a cornerstone of his
            daily routine. The bread is excellent, but it is the brief
            human connection that keeps him coming back.
            ---
        }
    }

Common prose tags:

- `---perspective`: How a participant views the relationship
- `---history`: Background of the relationship
- `---dynamics`: How the relationship functions
- `---notes`: Design or development notes

Note: In this syntax, perspective fields are inside participant blocks (not separate `self`/`other` blocks).

## Complete Examples

### Simple Friendship

    relationship Friendship {
        Martha
        NeighborBaker

        bond: 0.6
        years_known: 10
    }

### Marriage with Roles

    relationship Marriage {
        Martha as spouse
        David as spouse

        bond: 0.9
        anniversary: "2015-06-20"
        children: 2
    }

### Parent-Child with Perspectives

    relationship ParentChild {
        Martha as parent self {
            responsibility: 1.0
            protective: 0.9
            anxiety_level: 0.6
        } other {
            dependent: 0.8
            mature_for_age: 0.7
        }

        Tommy as child self {
            seeks_independence: 0.7
            appreciates_parent: 0.9
        } other {
            feels_understood: 0.6
            wants_more_freedom: 0.8
        }

        bond: 0.95
        years_together: 8
    }

### Employer-Employee

    relationship EmployerEmployee {
        Martha as employer self {
            authority: 0.9
            satisfaction_with_employee: 0.85
        } other {
            respect: 0.8
            trust: 0.85
        }

        Elena as employee self {
            job_satisfaction: 0.8
            career_growth: 0.7
        } other {
            respects_boss: 0.9
            appreciates_flexibility: 0.95
        }

        workplace: "Martha's Bakery"
        salary: 45000
        employment_start: "2023-01-15"
    }

### Complex Multi-Perspective

    relationship MentorApprentice {
        Martha {
            role: mentor
            teaching_style: "patient"
            investment: 0.9

            ---perspective
            Martha sees Elena as the daughter she might have had in
            the trade. She recognizes the same passion she felt at
            that age and pushes Elena harder because she knows the
            talent is there. Every correction comes from love.
            ---
        }

        Elena {
            role: apprentice
            dedication: 0.9
            anxiety: 0.4

            ---perspective
            Elena idolizes Martha's skill but fears disappointing
            her. Every morning she arrives thirty minutes early to
            practice techniques before Martha gets in. She keeps a
            notebook of every correction, reviewing them each night.

            "I want to be half as good as her someday" -- this quiet
            ambition drives everything Elena does.
            ---
        }

        bond: 0.85
    }

### Business Rivalry

    relationship BakeryRivalry {
        Martha {
            role: established_baker
            aware_of_competition: true
            respects_rival: 0.6

            ---perspective
            Martha views the new bakery across town as healthy
            competition. She respects their pastry work but knows
            her sourdough is unmatched. The rivalry pushes her to
            keep innovating.
            ---
        }

        RivalBaker {
            role: newcomer
            wants_to_surpass: true
            studies_martha: 0.8

            ---perspective
            The rival baker moved to town specifically because of
            Martha's reputation. They study her techniques, buy her
            bread to analyze it, and dream of the day a customer
            chooses their loaf over Martha's sourdough.
            ---
        }

        bond: 0.3
    }

### Multi-Party Family

    relationship BakerFamily {
        Martha as parent
        David as parent
        Tommy as child
        Elena as child

        household: "Baker Residence"
        family_bond: 0.95
        dinner_time: 18:00

        ---dynamics
        A loving queer family running a bakery together. Martha and
        David met at culinary school, married, and adopted Tommy and
        Elena. The whole family works at the bakery on weekends.
        ---
    }

### Co-Owners Partnership

    relationship BakeryPartnership {
        Martha {
            role: co_owner
            specialty: "bread"
            handles_finances: true

            ---perspective
            Martha and Jane complement each other perfectly. Martha
            handles the bread and business side while Jane creates
            the pastries that draw customers in. Together they have
            built something neither could alone.
            ---
        }

        Jane {
            role: co_owner
            specialty: "pastries"
            handles_creativity: true

            ---perspective
            Jane considers Martha the steady foundation of their
            partnership. While Jane experiments and creates, Martha
            ensures the bakery runs like clockwork. Their different
            strengths make the bakery stronger.
            ---
        }

        bond: 0.9
    }

## Participant Types

Participants can be:

1. Characters: Most common
2. Institutions: Organizations in relationships
3. Locations: Less common, but valid (e.g., “GuardianOfPlace”)

    relationship GuildMembership {
        Elena as member
        BakersGuild as organization

        membership_since: "2023-01-01"
        standing: "good"
        dues_paid: true
    }

## Field Resolution

When a relationship is resolved, fields are merged:

1. Relationship shared fields apply to all participants
2. Participant `self` blocks apply to that participant
3. Participant `other` blocks describe how that participant views others

Example:

    relationship Example {
        Martha as friend self {
            loyalty: 0.9
        } other {
            trust: 0.8
        }
        Gregory as friend

        bond: 0.85
    }

Resolution:

- Martha gets: `loyalty: 0.9` (from self), `trust: 0.8` (towards Gregory, from other), `bond: 0.85` (shared)
- Gregory gets: `bond: 0.85` (shared)
- Relationship gets: `bond: 0.85`

## Validation Rules

1. At least two participants: Relationships require ≥2 participants
2. Participants exist: All participant names must reference defined entities
3. Unique participant names: Each participant appears at most once
4. Field type consistency: Fields must have valid value types
5. No circular relationships: Avoid infinite relationship chains (warning)
6. Self/other completeness: If using `self`/`other`, both blocks should be present (best practice)

## Use Cases

### Social Networks

    relationship BakerFriendship {
        Martha
        Gregory
        bond: 0.8
    }

    relationship SupplierPartnership {
        Martha
        Farmer_Jenkins
        bond: 0.7
    }

    relationship BakeryRivalry {
        Martha
        RivalBaker
        bond: 0.2
        competitive: true
    }

### Family Structures

    relationship ParentChild {
        Martha as parent
        Tommy as child
        bond: 0.95
    }

    relationship Siblings {
        Tommy as older_sibling
        Elena as younger_sibling
        bond: 0.85
        rivalry: 0.3
    }

### Power Dynamics

    relationship Vassalage {
        King as lord self {
            grants: "protection"
            expects: "loyalty"
        } other {
            trusts: 0.6
        }

        Knight as vassal self {
            swears: "fealty"
            expects: "land"
        } other {
            respects: 0.9
        }

        oath_date: "1205-03-15"
    }

### Asymmetric Awareness

    relationship StalkingVictim {
        Stalker as pursuer self {
            obsession: 0.95
            distance_maintained: 50  // meters
        } other {
            believes_unnoticed: true
        }

        Victim as unaware_target self {
            awareness: 0.0
        }

        danger_level: 0.8
    }

## Best Practices

### 1. Use Descriptive Relationship Names

Avoid:

    relationship R1 { ... }
    relationship MarthaGregory { ... }

Prefer:

    relationship Friendship { ... }
    relationship ParentChild { ... }
    relationship MentorApprentice { ... }

### 2. Use Roles for Clarity

    relationship Marriage {
        Martha as spouse
        David as spouse
    }

Better than:

    relationship Marriage {
        Martha
        David
    }

### 3. Shared Fields for Mutual Properties

    relationship Partnership {
        Martha
        Jane

        bond: 0.9           // Mutual bond
        years_together: 5   // Shared history
    }

### 4. Self/Other for Perspectives

    relationship TeacherStudent {
        Teacher as mentor self {
            patience: 0.8
        } other {
            potential: 0.9
        }

        Student as learner self {
            motivation: 0.7
        } other {
            admiration: 0.95
        }
    }

### 5. Prose Blocks for Rich Context

    relationship ComplexDynamic {
        Martha { ... }
        Jane { ... }

        ---dynamics
        Their relationship is characterized by mutual respect but
        divergent goals. Martha focuses on traditional bread while Jane
        pushes for experimental pastries, creating creative tension.
        ---
    }

## Cross-References

- Characters - Participants are typically characters
- Institutions - Institutions can participate
- Value Types - Field value types
- Expression Language - Querying relationships

## Related Concepts

- Bidirectional modeling: `self`/`other` blocks enable asymmetric perspectives
- Social simulation: Relationships drive character interactions
- Narrative depth: Prose blocks embed storytelling in relationship data
- Power dynamics: Roles and perspective fields model hierarchies
- Emotional bonds: Bond strength and trust metrics quantify connections