AI Development Guide

Build Commands

These are the commands you'll use most frequently when developing with ARO:

Architecture Overview

Understanding the project structure helps AI assistants provide better suggestions:

Sources/
├── AROParser/          # Core parser library
├── ARORuntime/         # Runtime execution (interpreter)
│   ├── Actions/        # Action protocol, registry, built-ins
│   ├── Core/           # ExecutionEngine, Context
│   ├── Events/         # EventBus, event types
│   ├── HTTP/           # Server (SwiftNIO), Client
│   ├── FileSystem/     # File operations, FileMonitor
│   ├── Sockets/        # TCP server/client
│   └── OpenAPI/        # Contract-first routing
├── AROCompiler/        # Native compilation (C code generation)
├── AROCRuntime/        # C-callable Swift runtime bridge
└── AROCLI/             # CLI (run, compile, check, build)

Examples/
├── HelloWorld/         # Single-file example
├── HTTPServer/         # HTTP server example
├── FileWatcher/        # File monitoring example
└── UserService/        # Multi-file application

Proposals/              # 29 evolution proposals
Documentation/          # Developer guides

Application Structure

An ARO application is a directory containing .aro files:

MyApp/
├── openapi.yaml       # OpenAPI contract (required for HTTP server)
├── main.aro           # Contains Application-Start (required)
├── users.aro          # Feature sets for user operations
├── orders.aro         # Feature sets for order operations
└── events.aro         # Event handler feature sets

Key Rules

• All .aro files in the directory are automatically discovered and parsed
• No imports needed - all feature sets are globally visible
• Exactly ONE Application-Start feature set per application
• Feature sets are triggered by events, not direct calls
• Contract-First HTTP: openapi.yaml is required for HTTP server

ARO Syntax Quick Reference

Feature Set

(Feature Name: Business Activity) {
    Action the <result> from/with/to the <object>.
    Return an <OK: status> with <result>.
}

Comments

(* This is a comment *)

(*
   Multi-line comments
   are also supported
*)

Event Handlers

(* Feature sets named after operationIds handle HTTP requests *)
(listUsers: User API) { ... }
(createUser: User API) { ... }

(* Handler suffix for domain events *)
(Send Email: UserCreated Handler) { ... }
(Process File: FileCreated Handler) { ... }

Action Semantic Roles

Happy Case Design

ARO code contains only the happy case. Errors are handled by the runtime. For example, when a user cannot be retrieved from the repository, the server returns: Can not retrieve the user from the user-repository where id = 530.

Creating Custom Actions

When extending ARO with new actions, follow this pattern:

public struct MyAction: ActionImplementation {
    public static let role: ActionRole = .own
    public static let verbs: Set<String> = ["MyVerb"]
    public static let validPrepositions: Set<Preposition> = [.with, .from]

    public init() {}

    public func execute(
        result: ResultDescriptor,
        object: ObjectDescriptor,
        context: ExecutionContext
    ) async throws -> any Sendable {
        // Get input from context
        let input: String = try context.require(object.identifier)

        // Process and bind result
        let output = process(input)
        context.bind(result.identifier, value: output)

        // Emit event
        context.emit(MyEvent(value: output))

        return output
    }
}

// Register
ActionRegistry.shared.register(MyAction.self)

Concurrency

All core types (SymbolTable, Token, AST nodes, ActionImplementation) are Sendable for Swift 6.3 concurrency safety.

Tips for AI Assistants

• Always reference the CLAUDE.md file for project context
• Feature sets should be named after operationId values in openapi.yaml
• Use the Keepalive action for long-running servers
• Remember that ARO code is the happy path - don't add error handling
• Check the Proposals/ directory for detailed language specifications