# TURN — Temporal Unified Resource Notation

> Musical notation for AI agent orchestration. TURN scores describe multi-agent workflows the way sheet music describes a symphony.

## Overview

TURN provides a notation system where agents are musicians, workflows are scores, turns are measures, and cognition is a consumable resource with explicit cost tiers.

## Core Symbols

| Symbol | Name | Meaning |
|--------|------|---------|
| ◉ | Expensive cognition | Full LLM reasoning (Sonnet/Opus) |
| ○ | Cheap cognition | Lightweight model (Haiku) |
| ▷ | Inject | Push data into agent context |
| ◁ | Observe | Read from knowledge graph |
| ■ | Output | Produce final result |
| ⟳ | Flywheel | Learning loop |
| 💭 | Thinking | Extended reasoning (thinking tokens) |
| ♯ | Constraint | Active constraint (key signature) |

## Score Structure

A TURN score has:
- **Clef** — atoms in scope (e.g., CodeAtom, ConstraintAtom)
- **Key Signature** — active constraints
- **Time Signature** — turn budget, token budget, thinking enabled
- **Tracks** — agent lanes (one per archetype)
- **Measures** — turns containing events

Example:
```
𝄞 [CodeAtom, ConstraintAtom]
♯code_quality
10/30K💭

Scouts:     ║ ○◁AKG │ ·     │ ○◁AKG │...║
Main Agent: ║ · ◉💭  │ ◉     │ · ◉💭  │...║
Validators: ║ ·     │ · ○○○ │ ·     │...║
```

## Helper Archetypes (Cortex Model)

Six helper patterns augment a main agent:

1. **Scout** (before) — Pre-fetch context from knowledge graph
2. **Lookout** (before) — Detect blocking issues
3. **Speculator** (during) — Pre-compute decision branches
4. **Validator** (during) — Check outputs against constraints
5. **Scribe** (during) — Capture learnings as ObservationAtoms
6. **Librarian** (continuous) — Manage context window

All helpers use cheap cognition (○) to support expensive main agent cognition (◉).

## Trigger Language (TTL)

Graph-native triggers enable the knowledge graph to watch itself:

```
@trigger ObservationAtom
  WHEN confidence >= 0.9 AND 'limitation' IN tags
  ACTUATE {
    @agent: { query: "AgentAtom WHERE 'constraint_proposer' IN tags", tier: "cheap" }
    THEN
    @system: { operation: "create", atom_type: "ConstraintAtom" }
  }
```

Actuator types: @agent, @system, @human, @schedule, @message, @trigger

## Flywheel

Execute → Observe → Constrain → Route

Agents execute tasks, scribes observe patterns, high-confidence observations promote to constraints via triggers, and constraints update the router. The graph learns autonomously.

## AKG Atoms

- **ScoreAtom** — Complete orchestration pattern (sheet music)
- **PatternAtom** — Reusable helper archetype definition
- **TriggerAtom** — Graph-native actuator rules

All atoms support semantic vector search for discovery.

## Platform Mapping

| Concept | ADAMAS (native) | LangChain | CrewAI |
|---------|-----------------|-----------|--------|
| Score | ScoreAtom | Chain/Graph | Crew |
| Track | Agent + Config | Agent/Tool | Agent + Role |
| Measure | Restate step | Chain step | Task |
| Trigger | TriggerAtom | Callback | — |

## Links

- Specification: https://turn.dev/spec/
- Triggers: https://turn.dev/triggers/
- Archetypes: https://turn.dev/archetypes/
- Dashboard: https://turn.dev/dashboard/
- AKG Atoms: https://turn.dev/atoms/
- GitHub: https://github.com/pyramidal-io/TURN

## Related Standards

- [AKG](https://akg.dev) — Atomic Knowledge Graph
- [DGP](https://dgp.dev) — Domain Graph Protocol
- [ADAMAS](https://adamas.network) — Adaptive Decentralized Architecture for Multi-Agent Systems

---

License: Apache 2.0 · Version: 0.1.0 · Pyramidal Inc.