TURN Notation Specification

1. Introduction

1.1 The Problem

Agent systems represent a new computational paradigm with unique characteristics: discrete temporal structure, bounded cognitive resources, probabilistic outputs, learning dynamics, and multi-agent coordination.

Existing notations fail to capture these dynamics:

1.2 The Solution

TURN adapts musical notation concepts to agent orchestration—staves become agent lanes, measures become turns, notes become cognition events, clefs declare knowledge context, and key signatures enforce constraints.

1.3 Goals

1. Framework-agnostic — Express patterns independent of implementation
2. Human-readable — Visual notation that communicates at a glance
3. Machine-executable — Precise semantics for runtime interpretation
4. Analytically useful — Enable comparison, benchmarking, optimization
5. Pedagogically effective — Teach agent orchestration concepts

2. Design Principles

2.1 Turns as the Atomic Unit

The turn is the fundamental unit of agent time—an atomic reasoning episode where an agent receives input, processes it, and produces output. All temporal relationships are expressed relative to turn boundaries.

│ Turn N │ Turn N+1 │ Turn N+2 │

2.2 Cognition as a Consumable Resource

Agent reasoning consumes resources: tokens, time, money. TURN makes resource consumption visible through explicit notation, not hidden in implementation details.

2.3 Knowledge as First-Class

Knowledge atoms (data, decisions, constraints, observations) are first-class entities that define context, constrain behavior, and accumulate learning.

2.4 Agents as Musicians

TURN adopts the metaphor of orchestral performance:

• Composer — Writes requirements, defines orchestration patterns
• Conductor — Interprets requirements, directs sessions, handles dynamics
• Musicians — Execute their parts, respond to direction, provide feedback
• Score — The shared notation between all three roles

2.5 The Graph Watches Itself

Agent systems should be self-aware. The knowledge graph can trigger actuators, launch agents, and orchestrate responses based on its own state changes.

3. Core Primitives

3.1 Cognition Symbols

Main Agent:  │ ◉ ◉ ◉ │ ◉ ◉ · │
Scout:       │ ○ ○ · │ · · · │

3.2 Data Flow Symbols

3.3 Temporal Symbols

3.4 Resource Symbols

Main ◉ 🔋25              # Turn consumed 25 tokens
Context [████████░░] 80%   # Context 80% full
Main ◉💭 🔋100           # Extended thinking, high cost

4. Score Structure

4.1 Tracks (Staves)

Each agent type occupies a horizontal track, analogous to a staff in musical notation:

┌─────────────┬────────┬────────┬────────┬────────┐
│ Track Label │ Turn 1 │ Turn 2 │ Turn 3 │ Turn 4 │
├─────────────┼────────┼────────┼────────┼────────┤
│ Scouts      │ ○ ○    │ ·      │ ○ ○    │ ·      │
│ Main Agent  │ ·      │ ◉ ◉    │ ·      │ ◉      │
│ Scribes     │ ·      │ ○      │ ·      │ ○      │
│ Validators  │ ·      │ ·      │ ○ ○    │ ·      │
└─────────────┴────────┴────────┴────────┴────────┘

Standard track ordering (top to bottom): Scouts, Lookouts, Speculators, Main Agent (highlighted), Scribes, Validators, Librarians.

4.2 Measures (Turns)

Vertical bar lines delimit turns. All events within a measure occur during that turn. Events are ordered left-to-right (causal/temporal sequence). Multiple events on the same track indicate parallel actions.

4.3 Score Header

Every TURN score begins with a header declaring context:

𝄞 [ExecutionAtom, ObservationAtom, CodeAtom]   # Clef: atoms in scope
♯ConstraintAtom:no_hardcoded_secrets            # Key: active constraints
♯PolicyAtom:security_review_required
4/100 tokens                                     # Time: budget per turn

║: ... :║                                        # Score body

5. Semantic Extensions

5.1 Clefs (Atom Context)

The clef declares which knowledge atoms are in scope for a passage. Clef changes indicate context shifts:

𝄞 [RequirementAtom, CodeAtom]        # Working on implementation
│ ◉ ◉ │ ◉ │

𝄞 [ObservationAtom, ConstraintAtom]   # Now learning and constraining
│ ◉ ◉ ◉ │ ◉ ◉ │

5.2 Key Signatures (Constraints)

Key signatures declare active constraints and policies:

♯ConstraintAtom:layered_architecture    # Sharp = active/enforced
♯ConstraintAtom:no_circular_deps
♭PolicyAtom:allow_external_apis         # Flat = relaxed/disabled
♮                                        # Natural = constraints cleared

5.3 Time Signatures (Resource Budgets)

4/100      # 4 turns, 100 tokens total
∞/50       # Unlimited turns, 50 tokens per turn
8/200💭    # 8 turns, 200 tokens, thinking enabled

5.4 Dynamics (Cost Indicators)

6. Actuators & Triggers

Actuators are what cause knowledge transformations. The graph doesn't mutate itself—something must act.

Actuators can compose as chords (parallel) or sequences (chained):

@chord [@agent: scout, @agent: lookout, @system: policy_check] ON turn_start

@sequence [@agent: scribe → @system: threshold_check → @human: review IF flagged] ON execution_complete

See the full TURN Trigger Language (TTL) specification for syntax, built-in triggers, and the TriggerEngine implementation.

7. Pattern Library

7.1 Scout Enrichment

Scout ○──◁──AKG ──▷── Main ◉──▷── ■

7.2 Continuous Validation

Main:      │ ◉ ◉ ◉ │ ·     │ ◉ ◉ │
Validator: │ ·     │ ○◁Main │ ·   │  ← feedback

7.3 Flywheel Learning

|:
  │ Main ◉──▷ ExecutionAtom          │  # Execute
  │ Scribe ○◁Main ──▷ ObservationAtom│  # Observe
  │ @trigger: confidence≥0.9 → Constraint  │  # Constrain
  │ @schedule: daily → RouterAtom          │  # Route
:|

7.4 Speculative Branching

Main:       │ ◉ "considering A or B" │ ◉ decides A │
Speculator: │ ○ compute A path       │ ·           │
Speculator: │ ○ compute B path       │ · (discard) │

See the Helper Archetypes page for all six executable patterns.

8. Platform Mapping

TURN maps to multiple agent frameworks with varying fidelity:

9. Visual Rendering

TURN supports two rendering modes:

• TURN Score (static) — Rendered visual representation, analogous to sheet music. For documentation and design.
• TURN Runtime (live) — Real-time dashboard with playhead, WebSocket updates, and click-to-inspect symbols. See the Dashboard specification.

Renderers must support: track layout, measure grid, symbol rendering, color coding, animation (playhead), and interaction (click for details).

Appendix A: Complete Symbol Reference

Appendix B: Example Scores

Simple Implementation Pattern

TURN Score: Simple Implementation
Composer: RequirementAtom#req_001

𝄞 [RequirementAtom, CodeAtom]
♯code_review_required
8/200

║: Scout ○◁AKG │ Main ◉◉◉ │ Validator ○ │ Main ◉ ▷■ :║

Context: [░░░░░░░░░░] → [████████░░]
Tokens:  23 + 89 + 12 + 34 = 158/200 ✓

Flywheel Learning Pattern

TURN Score: Flywheel Learning
Composer: System

𝄞 [ExecutionAtom, ObservationAtom, ConstraintAtom, RouterAtom]
∞/∞  # Continuous operation

|:
  Execute:   │ Main ◉──▷ ExecutionAtom    │
  Observe:   │ Scribe ○◁Main ▷Observation │
  Constrain: │ @trigger: confidence≥0.9   │ → ConstraintAtom
  Route:     │ @schedule: daily           │ → RouterAtom
:|

Flywheel iterations: ∞
Learning rate: ~3 observations/session → ~0.5 constraints/day