AKG Atom Definitions

1. Design Rationale

TURN patterns could be stored as JSON configuration files. Making them atoms in the knowledge graph provides six critical capabilities:

All TURN atoms belong to the Navigate domain—they describe how to orchestrate workflows, not what to build (Stipulate) or how to implement (Articulate). They reside in the Runtime Database alongside WorkflowAtom, TaskAtom, and AgentAtom.

2. ScoreAtom

A complete TURN orchestration pattern—the "sheet music" for agent coordination. ScoreAtoms are content-addressed, versioned, and semantically searchable.

Score Header (Clef, Key, Time)

interface ScoreAtom {
  id: string;                    // Content-addressed hash
  name: string;                  // "security-audit-with-validation"
  description: string;
  version: string;               // Semantic version "1.0.0"

  // TURN Score Header
  clef: {
    atoms_in_scope: AtomReference[];     // [RequirementAtom, CodeAtom, ...]
  };
  key_signature: {
    active_constraints: ConstraintReference[];  // ConstraintAtom IDs
    active_policies: PolicyReference[];         // PolicyAtom IDs
  };
  time_signature: {
    max_turns?: number;          // null = unlimited
    token_budget?: number;
    cost_budget_usd?: number;
    thinking_enabled?: boolean;
  };

  // Classification
  pattern_type: PatternType;     // sequential | parallel_fanout | cortex | ...
  tags: string[];
  embedding?: number[];          // 1024-dim vector for semantic search
}

Tracks

Each track defines an agent lane in the score:

interface ScoreTrack {
  id: string;
  name: string;                  // "Scouts" | "Main Agent" | "Validators"
  agent_type: AgentArchetype;    // scout | lookout | speculator | main | validator | scribe | librarian
  tier: CognitionTier;           // "expensive" | "cheap" | "adaptive"
  agent_config?: {
    agent_id?: string;           // Specific AgentAtom ID
    skill_requirements?: string[];
    model_preference?: string;
  };
}

Measures & Events

Measures (turns) contain events positioned by beat within the turn:

interface ScoreMeasure {
  turn_number: number;
  events: ScoreEvent[];
  sync_point?: boolean;          // All tracks must complete before next turn
}

interface ScoreEvent {
  track_id: string;
  beat: number;                  // Position within turn (0-based)
  event_type: TurnEventType;     // cognition | data_flow | condition | trigger | sync | handoff

  cognition?: {
    symbol: '◉' | '○' | '◐' | '𝄽';
    thinking_budget?: number;
  };
  data_flow?: {
    direction: '▷' | '◁' | '■' | '□' | '◇';
    source?: AtomReference;
    target?: AtomReference;
  };
  condition?: {
    type: ConditionType;         // output_contains | confidence_threshold | budget_remaining | ...
    expression: string;
    on_true?: string;
    on_false?: string;
  };
  trigger?: string;              // TriggerAtom ID to fire
}

Pattern types classify scores by their orchestration strategy: sequential, parallel_fanout, fan_in_synthesis, iterative, conditional, meta_orchestration, hierarchical, dynamic_discovery, messaging, self_modifying, reasoning_guided, flywheel, cortex, or custom.

3. PatternAtom

A reusable sub-pattern (helper archetype) that can be composed into scores. PatternAtoms implement specific cognitive support roles.

Timing

interface PatternAtom {
  id: string;
  name: string;                  // "scout-enrichment" | "continuous-validation"
  archetype: AgentArchetype;     // scout | lookout | speculator | validator | scribe | librarian

  timing: {
    phase: 'before_main' | 'during_main' | 'after_main' | 'continuous';
    triggers?: string[];         // TriggerAtom IDs that can invoke this
    schedule?: {
      frequency: 'per_turn' | 'per_session' | 'on_demand';
      condition?: string;        // e.g. "task_complexity >= 'medium'"
    };
  };

  config: {
    tier: CognitionTier;
    model_preference?: string;
    token_budget?: number;
    parallel_instances?: number;
  };

  turn_notation: string;         // "○◁AKG ──▷── Main ◉"
  tags: string[];
  embedding?: number[];
}

Behavior

Patterns define pre-execution queries (fetching context from the AKG), injection rules (how context is formatted and delivered to the main agent), and post-execution actions (creating atoms, firing triggers, or sending messages):

behavior: {
  pre_queries?: {
    name: string;              // "relevant_constraints"
    query: string;             // Cypher or DGP query
    inject_as: string;         // Variable name in context
    cache_ttl?: number;        // Seconds to cache result
  }[];

  injection?: {
    target: 'main_context' | 'specific_track';
    format: 'structured' | 'natural_language';
  };

  post_actions?: {
    type: 'create_atom' | 'update_atom' | 'fire_trigger' | 'send_message';
    config: Record<string, any>;
  }[];
}

4. TriggerAtom

Graph-native actuator rules that make the graph self-mutating. TriggerAtoms observe atom changes and execute actuator chains in response.

Conditions

interface TriggerAtom {
  id: string;
  name: string;                  // "promote-observation-to-constraint"

  condition: {
    watch: {
      atom_type: string;         // "ObservationAtom"
      event: 'created' | 'updated' | 'deleted' | 'any';
    };
    when: TriggerPredicate;      // Simple or compound predicate
    with_context?: {             // Additional graph queries for context
      name: string;
      query: string;
    }[];
  };

  config: {
    enabled: boolean;
    priority: number;            // Higher = fires first
    debounce_ms?: number;
    max_fires_per_session?: number;
    requires_confirmation?: boolean;
  };
}

Predicates support simple comparisons (field op value), compound logic (and, or, not), and operators including eq, ne, gt, gte, lt, lte, contains, not_contains, in, not_in, matches, and exists.

Actuators

Each actuator specifies a type and configuration. Supported types: agent (launch reasoning), system (CRUD operations), human (approval gates), schedule (deferred execution), create_atom, update_atom, send_message, and fire_trigger (chaining). Each actuator can have a conditional guard.

5. Relationships

ScoreAtom Relationships

PatternAtom Relationships

TriggerAtom Relationships

6. Query Examples

Semantic Search for Patterns

CALL db.index.vector.queryNodes(
  'score_embedding_idx', 5, $query_embedding
) YIELD node, score
WHERE node.pattern_type IN ['parallel_fanout', 'fan_in_synthesis']
RETURN node.name, node.description, score
ORDER BY score DESC

Scores Using Scout Enrichment

MATCH (score:ScoreAtom)-[:USES_PATTERN]->(pattern:PatternAtom)
WHERE pattern.archetype = 'scout'
RETURN score.name, score.description, pattern.name

Active Triggers Watching ObservationAtom

MATCH (trigger:TriggerAtom)-[:WATCHES]->(watched)
WHERE trigger.condition.watch.atom_type = 'ObservationAtom'
  AND trigger.config.enabled = true
RETURN trigger.name, trigger.condition, trigger.actuators
ORDER BY trigger.config.priority DESC

Scores Satisfying a Requirement

MATCH (req:RequirementAtom {id: $req_id})<-[:SATISFIES]-(score:ScoreAtom)
OPTIONAL MATCH (score)-[:USES_PATTERN]->(pattern:PatternAtom)
RETURN score.name, score.pattern_type, collect(pattern.name) as helpers

Execution Analytics by Pattern Type

MATCH (score:ScoreAtom)<-[:EXECUTION_OF]-(exec:ExecutionAtom)
WITH score.pattern_type AS pattern, exec
RETURN pattern,
       count(exec) AS total_executions,
       avg(exec.duration_ms) AS avg_duration,
       avg(CASE WHEN exec.success THEN 1.0 ELSE 0.0 END) AS success_rate,
       sum(exec.cost_usd) AS total_cost
ORDER BY total_executions DESC

7. DGP Mutations

createScore

{
  "mutation": {
    "operation": "createScore",
    "input": {
      "name": "security-audit-with-validation",
      "description": "Parallel security scan with continuous validation",
      "pattern_type": "parallel_fanout",
      "clef": { "atoms_in_scope": [{"atom_type": "CodeAtom"}, {"atom_type": "ConstraintAtom"}] },
      "key_signature": { "active_constraints": [{"constraint_id": "no_hardcoded_secrets"}] },
      "time_signature": { "max_turns": 10, "token_budget": 50000 },
      "tracks": [
        {"name": "Scouts", "agent_type": "scout", "tier": "cheap"},
        {"name": "Main", "agent_type": "main", "tier": "expensive"},
        {"name": "Validators", "agent_type": "validator", "tier": "cheap"}
      ],
      "tags": ["security", "validation", "parallel"]
    }
  }
}

createPattern

{
  "mutation": {
    "operation": "createPattern",
    "input": {
      "name": "scout-enrichment",
      "archetype": "scout",
      "timing": { "phase": "before_main", "schedule": {"frequency": "per_turn"} },
      "behavior": {
        "pre_queries": [{
          "name": "relevant_decisions",
          "query": "MATCH (d:DecisionAtom) WHERE d.repo_id = $repo_id LIMIT 5 RETURN d",
          "inject_as": "prior_decisions"
        }]
      },
      "config": { "tier": "cheap", "parallel_instances": 3 },
      "turn_notation": "○◁AKG ──▷── Main ◉"
    }
  }
}

createTrigger

{
  "mutation": {
    "operation": "createTrigger",
    "input": {
      "name": "promote-observation-to-constraint",
      "condition": {
        "watch": { "atom_type": "ObservationAtom", "event": "created" },
        "when": {
          "type": "compound", "logic": "and",
          "predicates": [
            {"type": "simple", "field": "confidence", "operator": "gte", "value": 0.9},
            {"type": "simple", "field": "tags", "operator": "contains", "value": "limitation"}
          ]
        }
      },
      "actuators": [
        { "type": "agent", "config": { "agent_query": "...", "prompt_template": "..." } },
        { "type": "human", "condition": {"field": "impact", "operator": "eq", "value": "high"}, "config": {...} }
      ],
      "config": { "enabled": true, "priority": 100, "debounce_ms": 5000 }
    }
  }
}

discoverScores & executeScore

// Semantic search
{ "operation": "discoverScores",
  "input": { "query": "parallel validation for security scanning", "limit": 5 } }

// Execute a stored score
{ "operation": "executeScore",
  "input": { "score_id": "score_abc123", "inputs": {"repo_id": "repo_xyz"} } }

8. Integration with Existing Atoms

TURN atoms enhance three existing atom types with orchestration awareness:

WorkflowAtom

Gains a score_id reference to its TURN score and an inline pattern_type classification, linking static workflow definitions to their executable orchestration patterns.

ExecutionAtom

Tracks which score_id was executed, which PatternAtoms were activated (with activation count and duration), and which TriggerAtoms fired (with fire count and actuators executed). Enables per-pattern cost and success analytics.

SessionAtom

Tracks the active_score_id, the current_measure (which turn the session is in), and track_states (last event and context size per track). This powers the runtime dashboard's live view.

9. Indexing & Search

Vector search indexes enable semantic discovery of orchestration patterns:

// ScoreAtom semantic search
CALL db.index.vector.createNodeIndex(
  'score_embedding_idx', 'ScoreAtom', 'embedding', 1024, 'cosine'
)

// PatternAtom semantic search
CALL db.index.vector.createNodeIndex(
  'pattern_embedding_idx', 'PatternAtom', 'embedding', 1024, 'cosine'
)