# 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

```bnf
<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

```storybook
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

```storybook
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

```storybook
ParticipantName as role_name
```

### Examples

```storybook
relationship Marriage {
    Martha as spouse
    David as spouse

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

```storybook
relationship ParentChild {
    Martha as parent
    Tommy as child

    bond: 0.95
    guardianship: true
}
```

```storybook
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

```storybook
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:

```storybook
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:

```storybook
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

```storybook
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:

```storybook
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.

```storybook
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.

```storybook
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

```storybook
relationship Friendship {
    Martha
    NeighborBaker

    bond: 0.6
    years_known: 10
}
```

### Marriage with Roles

```storybook
relationship Marriage {
    Martha as spouse
    David as spouse

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

### Parent-Child with Perspectives

```storybook
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

```storybook
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

```storybook
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

```storybook
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

```storybook
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

```storybook
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")

```storybook
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:**
```storybook
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

```storybook
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

```storybook
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

```storybook
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

```storybook
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:**
```storybook
relationship R1 { ... }
relationship MarthaGregory { ... }
```

**Prefer:**
```storybook
relationship Friendship { ... }
relationship ParentChild { ... }
relationship MentorApprentice { ... }
```

### 2. Use Roles for Clarity

```storybook
relationship Marriage {
    Martha as spouse
    David as spouse
}
```

Better than:
```storybook
relationship Marriage {
    Martha
    David
}
```

### 3. Shared Fields for Mutual Properties

```storybook
relationship Partnership {
    Martha
    Jane

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

### 4. Self/Other for Perspectives

```storybook
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

```storybook
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](./10-characters.md) - Participants are typically characters
- [Institutions](./16-other-declarations.md#institutions) - Institutions can participate
- [Value Types](./18-value-types.md) - Field value types
- [Expression Language](./17-expressions.md) - 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
