Deal Engine DSL Reference v2.0

Document Purpose: Human-readable language reference for the Deal Engine Domain-Specific Language (DSL), supporting the Clause Type Composition Model.

Version: 2.1.0
Date: 2025-01-12

---

Table of Contents

1. Overview
2. Clause Types
3. Deal Types
4. Logic Elements
5. Expressions
6. Collection Operations
7. Cross-Clause References
8. Complete Examples
9. Versioning Context
10. Quick Reference

---

1. Overview

1.1 Purpose

The Deal Engine DSL defines reusable financial contract structures. It separates:

• Structure (how deals are computed) — defined in DSL
• Data (specific values) — provided in JSON instances

1.2 Key Concepts

Concept	Description
Clause Type	Reusable building block defining a specific financial arrangement
Deal Type	Template that suggests which clause types to use together
Deal Instance	Runtime combination of deal data + copied clause logic

1.3 Design Principles

1. Self-Containment: Deal instances contain all logic; no runtime catalog dependencies
2. Reactive Computation: Any data change triggers full recomputation
3. Explicit Interfaces: Clauses communicate only through declared outputs
4. Separation of Concerns: DSL defines structure; JSON provides specifics

1.4 File Structure

A DSL file contains one or more definitions:

// Comments use // or # or /* */

clause_type {
  // Clause type definition
}

deal_type {
  // Deal type definition
}

---

2. Clause Types

2.1 Structure Overview

clause_type {
  // Header - Identity and classification (required)
  id: show-settlement
  version: 1.0.0
  category: guarantee
  value_type: earning
  name: "Show Settlement"
  description: "Per-show guarantee vs percentage with settlement"
  
  // Schema - JSON Schema for clause data (optional)
  schema { ... }
  
  // Inputs - Deal-level data this clause needs (optional)
  inputs { ... }
  
  // Logic - Events, iterations, computations (optional)
  logic { ... }
  
  // Financial - Core financial structure (required for guarantee/contingent)
  financial { ... }
  
  // Outputs - Values exposed to deal level (optional)
  outputs { ... }
  
  // Template - Contract text rendering (optional)
  template { ... }
}

2.2 Header Fields

Field	Required	Description
id	Yes	Unique identifier (kebab-case recommended)
version	Yes	Semantic version (e.g., 1.0.0)
category	Yes	guarantee, contingent, or simple
value_type	Financial only	earning, reimbursement, third_party, or in_kind
name	Yes	Human-readable name
description	Yes	Brief description

Category definitions:

Category	Description	Example
guarantee	Certain payment when conditions met	Base fee, per diem
contingent	Conditional on event occurrence	Bonus, backend participation
simple	Non-financial terms	Exclusivity, territory rights

Value type definitions:

Value Type	Description	Commissionable
earning	Earned income	Yes
reimbursement	Expense pass-through	No
third_party	Payment to service provider	No
in_kind	Non-cash benefit	No

2.3 Schema Section

Defines the JSON Schema for data this clause operates on. Can be inline or referenced.

Inline schema:

schema {
  """
  {
    "type": "object",
    "required": ["shows", "artist_percentage"],
    "properties": {
      "shows": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "guarantee": { "type": "number" },
            "gross_revenue": { "type": ["number", "null"] },
            "earned": { "type": ["number", "null"] }
          }
        }
      },
      "artist_percentage": { "type": "number" }
    }
  }
  """
}

Referenced schema:

schema {
  ref: "https://schemas.uta.com/clause-types/show-settlement/1.0.0.json"
}

2.4 Inputs Section

Declares deal-level data and cross-clause references this clause needs.

inputs {
  // Deal-level field references
  effective_date: deal.dates.effective_date
  currency: deal.currency
  talent_name: deal.parties.talent.name
  
  // Cross-clause references (only declared outputs accessible)
  tour_guarantee: @tour_terms.total_guarantee
}

Syntax patterns:

Pattern	Example	Description
Deal field	deal.parties.talent.name	Access deal-level JSON data
Clause output	@clause_id.output_name	Reference another clause's output
Multi-clause	@clause_type[*].output	Reference all instances of a clause type

2.5 Logic Section

Contains the computational logic: variables, iterations, events, and computations.

logic {
  // Local variables
  var settlement_threshold = 1000
  
  // Iterate over collections
  for_each show in shows {
    // Item-scoped events
    event {
      name: show_settled_{show.id}
      description: "Show has been settled"
      condition: show.settled == true
    }
    
    // Item-scoped computations
    computations {
      metric show.artist_share = (show.gross_revenue - show.expenses) * artist_percentage
      metric show.earned = max(show.guarantee, show.artist_share ?? 0)
    }
  }
  
  // Clause-level events
  event {
    name: all_shows_settled
    description: "All shows have been settled"
    condition: count(shows where show.settled == true) == count(shows)
  }
  
  // Clause-level computations
  computations {
    output total_guarantee = sum(shows[*].guarantee)
    output total_earned = sum(shows[*].earned) ?? 0
  }
}

2.6 Financial Section

The core financial structure for guarantee and contingent clauses. Answers three questions:

1. How much? → amount
2. When earned? → earned
3. When received? → received

financial {
  amount: total_earned
  earned: on earning_schedule
  received: on receipt_schedule
  when: all_shows_settled
}

Field	Required	Description
amount	Yes	Expression evaluating to the financial value
earned	For earning value_type	Schedule for revenue recognition
received	Yes (except in_kind)	Schedule for cash receipt timing
when	Optional	Event guard for clause activation

The on keyword references a schedule defined in the clause's schema data.

2.7 Outputs Section

Declares values exposed to deal-level logic and other clauses.

outputs {
  total_guarantee: number
  total_earned: number
  all_shows_settled: boolean
}

Note: Values from the financial section (amount, earned, received) are automatically exposed as outputs.

2.8 Template Section

Contract text with template interpolation.

template {
  """
  PERFORMANCE COMPENSATION
  
  For each performance, Artist shall receive the greater of:
  (a) A guarantee of the amount specified per show, or
  (b) {{ percent(artist_percentage) }} of net revenues
  
  {{ for show in shows }}
  - {{ show.venue }}: Guarantee {{ money(show.guarantee, currency) }}
  {{ end }}
  
  Total: {{ money(total_earned, currency) }}
  """
}

---

3. Deal Types

3.1 Structure Overview

deal_type {
  // Header
  id: music-touring
  version: 1.0.0
  name: "Music Touring Deal"
  description: "Multi-show touring agreement"
  department: music
  tags: [touring, live-events]
  
  // Schema - Deal-level data structure
  schema { ... }
  
  // Suggested Clauses - Commonly-used clause types
  suggested_clauses { ... }
  
  // Logic - Deal-level aggregation
  logic { ... }
  
  // Outputs - Deal-level computed values
  outputs { ... }
}

3.2 Header Fields

Field	Required	Description
id	Yes	Unique identifier
version	Yes	Semantic version
name	Yes	Human-readable name
description	Yes	Brief description
department	No	Organizational department
tags	No	Searchable keywords

3.3 Suggested Clauses Section

Lists clause types commonly used with this deal type. These are suggestions, not requirements.

suggested_clauses {
  {
    type: show-settlement
    cardinality: one
    required: true
    description: "Per-show guarantee vs percentage"
  }
  {
    type: tour-versus
    cardinality: one
    required: false
    depends_on: [show-settlement]
  }
  {
    type: tiered-bonus
    cardinality: many
    required: false
    description: "Performance-based bonus groups"
  }
}

Field	Description
type	Clause type ID to suggest
cardinality	one (single instance) or many (multiple instances)
required	Whether this clause is typically mandatory
description	Why this clause is suggested
depends_on	Other clauses that should be included first

3.4 Deal-Level Logic

Aggregates values from clause instances.

logic {
  computations {
    output total_guaranteed = sum(@show_settlement.total_guarantee ?? 0,
                                   @tour_versus.guarantee ?? 0)
    output total_earned = sum(@show_settlement.total_earned ?? 0,
                              @tour_versus.versus_earned ?? 0,
                              @tiered-bonus[*].earned ?? 0)
  }
  
  event {
    name: deal_complete
    description: "All components settled"
    condition: @show_settlement.all_settled && @tour_versus.settled
  }
}

---

4. Logic Elements

4.1 Variables

Declare local variables with optional initial values.

var settlement_threshold = 1000
var artist_percentage
var running_total = 0

Variables declared in logic are scoped to that clause.

4.2 For Each Blocks

Iterate over collections in the clause data.

for_each show in shows {
  // Events scoped to this item
  event {
    name: show_occurred_{show.id}
    description: "Show has occurred"
    condition: show.occurred == true
  }
  
  // Computations scoped to this item
  computations {
    metric show.net_revenue = show.gross_revenue - show.expenses
    metric show.artist_share = show.net_revenue * artist_percentage
    metric show.earned = if show.settled then max(show.guarantee, show.artist_share) else null
  }
}

Key concepts:

Aspect	Description
Item variable	show in for_each show in shows
Collection	shows — must be an array in clause data
Item access	show.field accesses fields on current item
Field assignment	metric show.earned = ... populates computed field
Dynamic naming	show_occurred_{show.id} creates unique event names

Nested for_each is supported:

for_each group in bonus_groups {
  for_each tier in group.tiers {
    event {
      name: tier_achieved_{group.id}_{tier.id}
      condition: tier.threshold <= group.actual_value
    }
    computations {
      metric tier.achieved = tier.threshold <= group.actual_value
    }
  }
  computations {
    metric group.earned = max(group.tiers where tier.achieved == true, tier.amount) ?? 0
  }
}

4.3 Events

Define conditions that track state.

event {
  name: box_office_milestone_reached
  description: "Box office crosses $100M threshold"
  condition: worldwide_box_office >= 100000000
}

Event state model:

State	Meaning
unknown	Not yet determinable (initial state)
true	Condition satisfied
false	Condition definitively not satisfied

Event types by condition:

Type	Condition Pattern	Example
Calculated	Expression on data	gross_revenue >= threshold
External	Boolean variable	production_completed
Compound	References other events	event_a && event_b

4.4 Computations

Calculate derived values.

computations {
  // Metrics are intermediate values
  metric net_revenue = gross_revenue - expenses
  metric artist_share = net_revenue * artist_percentage
  
  // Outputs are exposed to deal level
  output total_earned = sum(shows[*].earned) ?? 0
  output all_settled = count(shows where show.settled) == count(shows)
}

Keyword	Scope	Description
metric	Internal	Intermediate calculation, not exposed
output	External	Exposed to deal level and other clauses

---

5. Expressions

5.1 Arithmetic

Operator	Description	Example
+	Addition	a + b
-	Subtraction	a - b
*	Multiplication	a * b
/	Division	a / b
- (unary)	Negation	-a

Precedence (highest to lowest): unary -, * /, + -

5.2 Comparison

Operator	Description
==	Equal
!=	Not equal
<	Less than
<=	Less than or equal
>	Greater than
>=	Greater than or equal

5.3 Boolean

Operator	Description	Example
&&	Logical AND	a && b
||	Logical OR	a || b
!	Logical NOT	!a

5.4 Null Coalescing

The ?? operator provides a default when the left operand is null.

artist_share ?? 0                    // Returns 0 if artist_share is null
sum(shows[*].earned) ?? 0            // Returns 0 if sum is null (all values null)
@other_clause.output ?? default_value // Default if clause doesn't exist

5.5 Conditional (If-Then-Else)

if condition then value_if_true else value_if_false

Examples:

// Simple conditional
metric earned = if settled then artist_share else null

// Nested conditional
metric tier_bonus = 
  if tickets_sold >= 15000 then 20000
  else if tickets_sold >= 13000 then 15000
  else if tickets_sold >= 11000 then 10000
  else 0

// With null coalescing
metric safe_share = if settled then (artist_share ?? 0) else 0

5.6 Null Propagation

Arithmetic operations propagate null:

Expression	If any operand is null	Result
a + b	Propagates	null
a * b	Propagates	null
a > b	Propagates	null
a ?? default	Uses default	default

---

6. Collection Operations

6.1 Overview

Collection operations aggregate values from arrays.

Function	Description	Empty Collection	All Nulls
sum()	Sum of values	0	null
count()	Count of items	0	Count
max()	Maximum value	null	null
min()	Minimum value	null	null

6.2 Basic Syntax

// Sum all values in a field
sum(shows[*].guarantee)

// Count all items
count(shows)

// Max/min
max(shows[*].earned)
min(tiers[*].threshold)

6.3 With Where Clause

Filter items before aggregating.

// Sum only settled shows
sum(shows where show.settled == true, show.earned)

// Count achieved tiers
count(tiers where tier.achieved == true)

// Max of filtered set
max(bonus_groups where group.triggered == true, group.amount)

Syntax: function(collection where condition, field)

6.4 Null Handling

Collection operations skip null values:

// If shows[*].earned = [100, null, 200, null]
sum(shows[*].earned)        // Returns 300 (nulls skipped)
count(shows)                // Returns 4 (counts all items)
sum(shows[*].earned) ?? 0   // Use ?? for safety when all might be null

---

7. Cross-Clause References

7.1 Single Clause Reference

Reference an output from another clause instance.

// In deal-level logic or clause inputs
@show_settlement.total_earned
@tour_versus.versus_amount

Syntax: @clause_id.output_name

7.2 Multi-Instance Reference

When a clause type has cardinality: many, reference all instances.

// Sum across all bonus group instances
sum(@tiered-bonus[*].earned ?? 0)

// Check if all are complete
count(@tiered-bonus[*] where group.complete == true)

Syntax: @clause_type[*].output_name

7.3 With Null Coalescing

Always use ?? when referencing clauses that might not exist or have null outputs.

// Safe references
@optional_clause.amount ?? 0
sum(@tiered-bonus[*].earned ?? 0)

// In deal-level aggregation
output total = @clause_a.amount ?? 0 + @clause_b.amount ?? 0

7.4 In Inputs Section

Declare cross-clause dependencies explicitly.

inputs {
  show_totals: @show_settlement.total_earned
  all_bonuses: @tiered-bonus[*].earned
}

These create dependencies resolved at deal instance creation.

7.5 The "Deal Must Compile" Principle

All cross-clause references must resolve when a deal is created or modified. If a referenced clause doesn't exist or doesn't expose the referenced output, the deal will not compile and the change is rejected.

For optional clauses, always use null coalescing:

// In deal-level logic
total_earnings = @base_fee.amount + 
                 @performance_bonus.earned ?? 0 +    // Optional clause
                 @backend_participation.earned ?? 0  // Optional clause

This ensures deals remain valid even when optional clauses are omitted. See Section 9.4 for more details.

---

8. Complete Examples

8.1 Show Settlement Clause Type

clause_type {
  id: show-settlement
  version: 1.0.0
  category: guarantee
  value_type: earning
  name: "Show Settlement"
  description: "Per-show guarantee vs percentage with settlement"
  
  schema {
    """
    {
      "type": "object",
      "required": ["shows", "artist_percentage"],
      "properties": {
        "shows": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "venue", "date", "guarantee"],
            "properties": {
              "id": { "type": "string" },
              "venue": { "type": "string" },
              "date": { "type": "string", "format": "date" },
              "guarantee": { "type": "number", "minimum": 0 },
              "gross_revenue": { "type": ["number", "null"] },
              "expenses": { "type": ["number", "null"] },
              "occurred": { "type": "boolean", "default": false },
              "settled": { "type": "boolean", "default": false },
              "artist_share": { "type": ["number", "null"] },
              "earned": { "type": ["number", "null"] }
            }
          }
        },
        "artist_percentage": { "type": "number", "minimum": 0, "maximum": 1 },
        "earning_schedule": { "$ref": "#/definitions/schedule" },
        "receipt_schedule": { "$ref": "#/definitions/receipt_schedule" }
      }
    }
    """
  }
  
  inputs {
    currency: deal.currency
    tour_name: deal.tour_info.tour_name
  }
  
  logic {
    for_each show in shows {
      event {
        name: show_occurred_{show.id}
        description: "Show has occurred"
        condition: show.occurred == true
      }
      
      event {
        name: show_settled_{show.id}
        description: "Show has been settled"
        condition: show.settled == true
      }
      
      computations {
        metric show.net_revenue = show.gross_revenue - show.expenses
        metric show.artist_share = show.net_revenue * artist_percentage
        metric show.earned = if show.settled 
                             then max(show.guarantee, show.artist_share ?? 0)
                             else null
      }
    }
    
    event {
      name: all_shows_occurred
      description: "All scheduled shows have occurred"
      condition: count(shows where show.occurred == true) == count(shows)
    }
    
    event {
      name: all_shows_settled
      description: "All shows have been settled"
      condition: count(shows where show.settled == true) == count(shows)
    }
    
    computations {
      output total_guarantee = sum(shows[*].guarantee)
      output total_earned = sum(shows[*].earned) ?? 0
      output total_received = sum(shows where show.settled == true, show.earned) ?? 0
    }
  }
  
  financial {
    amount: total_earned
    earned: on earning_schedule
    received: on receipt_schedule
    when: all_shows_settled
  }
  
  outputs {
    total_guarantee: number
    total_earned: number
    total_received: number
    all_shows_occurred: boolean
    all_shows_settled: boolean
  }
  
  template {
    """
    PERFORMANCE COMPENSATION - {{ tour_name }}
    
    For each performance during the Tour, Artist shall receive the greater of:
    (a) The applicable guarantee amount, or
    (b) {{ percent(artist_percentage) }} of Net Revenues
    
    Scheduled Performances:
    {{ for show in shows }}
    {{ show.date }} - {{ show.venue }}
      Guarantee: {{ money(show.guarantee, currency) }}
      {{ if show.settled }}
      Settled Amount: {{ money(show.earned, currency) }}
      {{ end }}
    {{ end }}
    
    Total Guarantee: {{ money(total_guarantee, currency) }}
    Total Earned: {{ money(total_earned, currency) }}
    """
  }
}

8.2 Tiered Bonus Clause Type

clause_type {
  id: tiered-bonus
  version: 1.0.0
  category: contingent
  value_type: earning
  name: "Tiered Bonus"
  description: "Multi-tier bonus based on threshold achievement"
  
  schema {
    """
    {
      "type": "object",
      "required": ["group_name", "tiers", "actual_value"],
      "properties": {
        "group_name": { "type": "string" },
        "actual_value": { "type": ["number", "null"] },
        "selection_rule": { 
          "type": "string", 
          "enum": ["highest", "sum", "highest_plus_cumulative"],
          "default": "highest"
        },
        "tiers": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "name", "threshold", "amount"],
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" },
              "threshold": { "type": "number" },
              "amount": { "type": "number" },
              "cumulative": { "type": "boolean", "default": false },
              "achieved": { "type": ["boolean", "null"] }
            }
          }
        },
        "receipt_schedule": { "$ref": "#/definitions/receipt_schedule" }
      }
    }
    """
  }
  
  inputs {
    currency: deal.currency
  }
  
  logic {
    for_each tier in tiers {
      event {
        name: tier_achieved_{tier.id}
        description: "Tier threshold reached"
        condition: actual_value != null && actual_value >= tier.threshold
      }
      
      computations {
        metric tier.achieved = actual_value != null && actual_value >= tier.threshold
      }
    }
    
    event {
      name: any_tier_achieved
      description: "At least one tier achieved"
      condition: count(tiers where tier.achieved == true) > 0
    }
    
    computations {
      // Selection rule: highest achieved tier
      output earned = if selection_rule == "highest"
                      then max(tiers where tier.achieved == true, tier.amount) ?? 0
                      else if selection_rule == "sum"
                      then sum(tiers where tier.achieved == true, tier.amount) ?? 0
                      else 0  // highest_plus_cumulative handled separately
    }
  }
  
  financial {
    amount: earned
    received: on receipt_schedule
    when: any_tier_achieved
  }
  
  outputs {
    earned: number
    any_tier_achieved: boolean
  }
}

8.3 Music Touring Deal Type

deal_type {
  id: music-touring
  version: 1.0.0
  name: "Music Touring Deal"
  description: "Multi-show touring agreement with settlement and optional bonuses"
  department: music
  tags: [touring, live-events, settlement]
  
  schema {
    """
    {
      "type": "object",
      "required": ["parties", "dates", "currency", "tour_info"],
      "properties": {
        "parties": {
          "type": "object",
          "required": ["talent", "promoter"],
          "properties": {
            "talent": { "$ref": "authoritative://schemas/talent" },
            "promoter": { "$ref": "authoritative://schemas/promoter" },
            "agency": { "$ref": "authoritative://schemas/agency" }
          }
        },
        "dates": {
          "type": "object",
          "required": ["effective_date", "tour_start", "tour_end"],
          "properties": {
            "effective_date": { "type": "string", "format": "date" },
            "tour_start": { "type": "string", "format": "date" },
            "tour_end": { "type": "string", "format": "date" }
          }
        },
        "currency": { "type": "string", "enum": ["USD", "EUR", "GBP", "CAD"] },
        "tour_info": {
          "type": "object",
          "properties": {
            "tour_name": { "type": "string" },
            "tour_region": { "type": "string" },
            "headliner": { "type": "boolean" }
          }
        }
      }
    }
    """
  }
  
  suggested_clauses {
    {
      type: show-settlement
      cardinality: one
      required: true
      description: "Per-show guarantee vs percentage settlement"
    }
    {
      type: tour-versus
      cardinality: one
      required: false
      depends_on: [show-settlement]
      description: "Tour-level guarantee vs aggregate percentage"
    }
    {
      type: tiered-bonus
      cardinality: many
      required: false
      description: "Performance-based bonus tiers"
    }
    {
      type: expense-reimbursement
      cardinality: one
      required: false
      description: "Travel and production expense reimbursement"
    }
  }
  
  logic {
    event {
      name: tour_complete
      description: "All tour components settled"
      condition: @show_settlement.all_shows_settled && 
                 (@tour_versus.settled ?? true)
    }
    
    computations {
      output total_guaranteed = @show_settlement.total_guarantee ?? 0 +
                                @tour_versus.guarantee ?? 0
      
      output total_earnings = @show_settlement.total_earned ?? 0 +
                              @tour_versus.versus_earned ?? 0 +
                              sum(@tiered-bonus[*].earned ?? 0)
      
      output total_reimbursements = @expense-reimbursement.total_actual ?? 0
      
      output total_received = @show_settlement.total_received ?? 0 +
                              @expense-reimbursement.total_received ?? 0
      
      output total_pending = total_earnings - total_received
    }
  }
  
  outputs {
    total_guaranteed: number
    total_earnings: number
    total_reimbursements: number
    total_received: number
    total_pending: number
    tour_complete: boolean
  }
}

---

9. Versioning Context

9.1 Design-Time vs. Runtime

The DSL defines design-time artifacts:

Artifact	Defined In	Purpose
Clause Type	DSL	Reusable template for financial arrangements
Deal Type	DSL	Template suggesting clause compositions

Deal Instances are runtime artifacts stored as JSON. They contain copied logic from clause types and deal types, plus actual data and computed state.

Design-Time (DSL)              Runtime (JSON)
─────────────────              ──────────────
                              
  clause_type ──────copy────▶  clause.logic
  deal_type   ──────copy────▶  deal_logic
                              
  [Catalog]                    [Deal Instance]

9.2 Logic Freezing

When a deal instance is created:

1. Selected clause types have their logic copied into the instance
2. Deal-level logic is copied from the deal type
3. The instance becomes self-contained — no runtime catalog dependencies

This means:

• Updating a clause type in the catalog does not affect existing deals
• The exact logic that computed results is always preserved
• Deal instances can be evaluated independently

9.3 Instance Versioning

Deal instances have their own version chain, independent of catalog versioning:

Change	Creates New Instance Version
Data update (settlement entered)	Yes
Clause logic amended	Yes
Clause added/replaced/removed	Yes
Deal-level logic amended	Yes

Each version is immutable. The version chain provides a complete audit trail.

Note: Catalog versioning (clause type 1.0.0 → 1.1.0) and instance versioning (deal version 1 → 2 → 3) are separate concerns. Catalog versions affect future deals; instance versions track this deal's evolution.

9.4 The "Deal Must Compile" Principle

Cross-clause references (@clause.output) must resolve to declared outputs. This is validated:

• When a deal is created
• When a clause is added, replaced, or removed
• When deal-level logic is amended

If references cannot resolve, the change is rejected. Use null coalescing for optional clauses:

// Safe: handles case where bonus clause doesn't exist
total_bonus: @performance_bonus.earned ?? 0

// Unsafe: fails if clause is removed
total_bonus: @performance_bonus.earned

9.5 Implications for DSL Authors

When writing clause types and deal types:

Concern	Guidance
Output stability	Outputs are the contract between clauses; changing them may break existing deals
Optional clauses	Use ?? in deal-level logic for clauses that might not be included
Versioning	Use semantic versioning for clause types; breaking changes warrant major version bump
Self-containment	Don't assume access to catalog at runtime; all logic must be embedded

---

10. Quick Reference

10.1 Keywords

Category	Keywords
Top-level	clause_type, deal_type
Sections	schema, inputs, logic, financial, outputs, template, suggested_clauses, computations
Header fields	id, version, category, value_type, name, description, department, tags
Financial fields	amount, earned, received, when
Category values	guarantee, contingent, simple
Value types	earning, reimbursement, third_party, in_kind
Control flow	for_each, in, if, then, else, where
Declarations	var, metric, output, event
Functions	sum, count, max, min
Literals	true, false, null
Type annotations	number, boolean, string
Cardinality	one, many

10.2 Operators

Operator	Description	Precedence
??	Null coalescing	Lowest
||	Logical OR
&&	Logical AND
!	Logical NOT
== != < <= > >=	Comparison
+ -	Addition/Subtraction
* /	Multiplication/Division
- (unary)	Negation	Highest

10.3 Special Syntax

Syntax	Description	Example
@clause.output	Cross-clause reference	@show_settlement.total_earned
@clause_type[*].output	Multi-instance reference	@tiered-bonus[*].earned
deal.field.path	Deal-level data access	deal.parties.talent.name
item.field	Item access in for_each	show.guarantee
collection[*].field	Collection field access	shows[*].earned
name_{item.field}	Dynamic naming	show_settled_{show.id}
on schedule_name	Schedule reference	on earning_schedule

10.4 Collection Operations

Operation	Syntax	Empty	All Nulls
Sum	sum(coll[*].field)	0	null
Count	count(coll)	0	Count
Max	max(coll[*].field)	null	null
Min	min(coll[*].field)	null	null
Filtered	func(coll where cond, field)	Same	Same

---

Document History

• v2.1.0 (2025-01-12) - Added versioning context
  • New Section 9: Versioning Context (design-time vs runtime, logic freezing, instance versioning)
  • New Section 7.5: "Deal Must Compile" principle in Cross-Clause References
  • Renumbered Quick Reference to Section 10
• v2.0.0 (2025-01-09) - Initial release
  • Complete rewrite for Clause Type Composition Model
  • Added clause_type and deal_type top-level constructs
  • Added for_each with dynamic event naming
  • Added collection operations with where clauses
  • Added cross-clause reference syntax
  • Added null coalescing operator
  • Added if-then-else expressions
  • Added financial section with earned/received
  • Comprehensive examples