Actions

Action Categories

ARO actions are organized by their semantic role - the direction of data flow:

REQUEST Actions

These actions bring data from external sources into your feature set.

Extract

Pull data from a structured source:

Extract the <user-id> from the <request: parameters>.
Extract the <body> from the <request: body>.
Extract the <email> from the <user: email>.
Extract the <items> from the <order: lineItems>.

Retrieve

Fetch data from a repository or data store:

Retrieve the <user> from the <user-repository>.
Retrieve the <matching-user> from the <user-repository> where id = <user-id>.
Retrieve the <orders> from the <order-repository> where status = "pending".

Request

Make HTTP requests to external APIs:

Request the <data> from "https://api.example.com/resource".
Request the <users> from the <users-url>.
Request the <weather> from the <forecast-url> with { query: { city: <city> } }.

Read

Read from files:

Read the <content> from the <file: "./data.txt">.
Read the <config: JSON> from the <file: "./config.json">.
Read the <data: bytes> from the <file: "./image.png">.

Request

Make HTTP requests with method control:

(* GET request *)
Request the <data> from the <api-url>.

(* POST request with data *)
Request the <created> to the <api-url> with <payload>.

(* Explicit method: via <METHOD> *)
Request the <updated> via PUT the <api-url> with <update>.
Request the <removed> via DELETE the <api-url>.

Exec

Execute shell commands (ARO-0010):

Exec the <result> for the <command> with "ls -la".
Exec the <output> on the <system> with {
    command: "npm install",
    workingDirectory: "/app",
    timeout: 60000
}.

OWN Actions

These actions create or transform data within your feature set.

Create

Create new data structures:

Create the <user> with <user-data>.
Create the <response> with { message: "Success", code: 200 }.
Create the <order> with {
    items: <items>,
    total: <total>,
    customer: <customer-id>
}.

Compute

Perform calculations:

Compute the <total> for the <items>.
Compute the <hash> for the <password>.
Compute the <tax> for the <subtotal>.
Compute the <average> for the <values>.

Transform

Convert or map data:

Transform the <dto> from the <entity>.
Transform the <response> from the <data>.
Transform the <updated-user> from the <user> with <updates>.

Validate

Check data against rules:

Validate the <valid-user> for the <user-data>.
Validate the <valid-email> for the <email>.

(* ARO has no `if`. A guard rides on the statement it protects. *)
Return a <BadRequest: status> with <user-data> when not <valid-user>.

Compare

Compare values:

(* Compare binds a fresh result; it never rebinds an operand. *)
Compare the <password-match> from the <password-hash> against the <stored-hash>.
Compare the <signature-match> from the <signature> against the <expected-signature>.

(* <name: matches> is the boolean; <name: result> is equal / less / greater. *)
Return an <OK: status> for the <login> when <password-match: matches>.

Update

Modify existing data:

Update the <user> with <changes>.
Update the <order: status> with "shipped".

Sort

Order collections:

Sort the <sorted-users> from the <users> by <name>.
Sort the <sorted-numbers> for the <numbers>.

(* Descending is a qualifier on the result, not a `with` argument. *)
Sort the <ordered: descending> for the <numbers>.

Split

Split strings by regex delimiter (ARO-0037):

Split the <parts> from the <csv-line> by /,/.
Split the <words> from the <sentence> by /\s+/.
Split the <tokens> from the <code> by /[;,]+/.

Merge

Combine data structures:

Merge the <existing-user> with <update-data>.
Merge the <combined> from <list1> with <list2>.

Filter

Select matching elements from collections:

Filter the <active-users> from the <users> where <status> = "active".
Filter the <expensive> from the <products> where <price> > 100.

Map

Transform collection elements:

Map the <names> from the <users: name>.
Map the <emails> from the <customers: email>.

Reduce

Aggregate collections:

Reduce the <total> from the <items> with sum(<price>).
Reduce the <count> from the <orders> with count().

Group

Partition a collection into sub-collections by field value:

Group the <status-groups> from the <orders> by "status".
Group the <departments> from the <employees> by "department".

RESPONSE Actions

These actions send results back from your feature set.

Return

Return a result with status:

(* Success responses *)
Return an <OK: status> with <data>.
Return a <Created: status> with <resource>.
Return a <NoContent: status> for the <deletion>.

(* Error responses *)
Return a <BadRequest: status> with <errors>.
Return a <NotFound: status> for the <missing: resource>.
Return a <Forbidden: status> for the <unauthorized: access>.

Status Codes:

Throw

Throw an error:

Throw a <ValidationError> for the <invalid: input>.
Throw a <NotFoundError> for the <missing: user>.

(* Throw takes `for` only — the object names what failed. *)
Throw an <AuthError> for the <credentials>.

EXPORT Actions

These actions publish data or send to external systems.

Store

Save to a repository:

Store the <user> into the <user-repository>.
Store the <order> into the <order-repository>.
Store the <log-entry> into the <audit-log>.

Publish

Make variables globally available:

Publish as <current-user> <user>.
Publish as <app-config> <config>.

Log

Write to logs:

Log "User logged in" to the <console>.
Log <error> to the <console>.

Send

Send data to external destinations:

Send the <email> to the <user: email>.
Send the <notification> to the <push-service>.
Send the <data> to the <connection>.

Emit

Emit domain events:

Emit a <UserCreated: event> with <user>.
Emit an <OrderPlaced: event> with <order>.
Emit a <PaymentProcessed: event> with <payment>.

Delete

Remove data:

Delete the <user> from the <user-repository> where id = <user-id>.
Delete the <stale-key> from the <cache-entry>.

(* A file is deleted through the <file: path> object, like every
   other ARO-0036 file action — the result names the outcome. *)
Delete the <gone> from the <file: "./temp.txt">.

Write

Write content to files:

Write the <content> to the <file: "./output.txt">.
Write the <data: JSON> to the <file: "./data.json">.

Append

Append content to files:

Append the <log-line> to the <file: "./app.log">.
Append the <entry> to the <file: "./data.csv">.

File Operations

Actions for file system operations (ARO-0036).

List

List directory contents:

Create the <dir-path> with "./uploads".
List the <entries> from the <directory: dir-path>.
List the <aro-files> from the <directory: src-path> matching "*.aro".
List the <all-files> from the <directory: path> recursively.

Stat

Get file or directory metadata:

Stat the <info> for the <file: "./document.pdf">.
Stat the <dir-info> for the <directory: "./src">.

Exists

Check if a file or directory exists:

Exists the <found> for the <file: "./config.json">.
Exists the <dir-exists> for the <directory: "./output">.

CreateDirectory

Create directories (with parent directories):

CreateDirectory the <output-dir> to the <path: "./output/reports/2024">.

Copy

Copy files or directories:

Copy the <file: "./template.txt"> to the <destination: "./copy.txt">.
Copy the <directory: "./src"> to the <destination: "./backup/src">.

Move

Move or rename files and directories:

Move the <file: "./draft.txt"> to the <destination: "./final.txt">.
Move the <directory: "./temp"> to the <destination: "./processed">.

Service Actions

These actions interact with runtime services.

Start

Start a service:

(* The HTTP server's routes and port come from openapi.yaml. *)
Start the <http-server> with { }.

(* A TCP socket server takes its port in the `with` record. *)
Start the <socket-server> with { port: 9000 }.

Watch

Monitor a directory:

(* Watching a directory starts the file-monitor service; the path
   is the object. File events then reach `File Event Handler`
   feature sets. *)
Start the <file-monitor> with "./uploads".

Listen / Connect

(* Inbound: start the server, then keep the process alive. *)
Start the <socket-server> with { port: 9000 }.
Keepalive the <application> for the <events>.

(* Outbound: Connect binds the connection it opened. *)
Connect the <conn> to the <host> with { port: 5432 }.

Close

Close connections:

Close the <session> with <connection>.
Close the <socket-server> with <application>.

Broadcast

Send to all connections:

Broadcast the <message> to the <socket-server>.
Broadcast the <notification> to the <chat-server> with "User joined".

Call

Call external APIs (ARO-0016):

Call the <result> via <UserAPI: POST /users> with <user-data>.
Call the <response> via <PaymentAPI: POST /charge> with <payment>.

Keepalive

Keep application running for events (ARO-0005):

Keepalive the <application> for the <events>.

Blocks until shutdown signal (SIGINT/SIGTERM), essential for servers and file watchers.

State Actions

Actions for state machine transitions.

Accept

Accept a state transition:

(* The result names the transition; the object is the field holding
   the current state. Transitions are declared as an OpenAPI enum. *)
Accept the <transition: draft_to_submitted> on <document: status>.
Accept the <transition: submitted_to_approved> on <document: status>.

Test Actions

Actions for testing and assertions.

Given / When / Then

BDD-style test structure:

(* Given binds an input, When runs the feature set under test,
   Then asserts the result. *)
Given the <text> with "hello".
When the <len> from the <get-length>.
Then the <len> with 5.

Assert

Assert conditions:

Assert the <valid> for the <email-result>.
Assert the <total> with 42.

Git Actions

Native version control via libgit2 (ARO-0080). The bare <git> system object discovers the enclosing repository upward from the current working directory (like the git CLI); use <git: "/path"> for an explicit repository (opened as given, no discovery).

Status, Log, Branch

Inspect the working tree using Retrieve:

Retrieve the <status> from the <git>.
Retrieve the <log> from the <git>.
Retrieve the <branch> from the <git>.

Stage and Commit

Stage files and create commits:

Stage the <files> to the <git> with ".".
Commit the <result> to the <git> with "feat: add feature".

Pull and Push

Synchronise with remotes (delegates to the git CLI):

Pull the <updates> from the <git>.
Push the <result> to the <git>.

Clone, Checkout, Tag

Branching, tagging, and cloning repositories:

Clone the <repo> from the <git> with {
    url: "https://github.com/user/repo.git",
    path: "./cloned"
}.
Checkout the <branch> from the <git> with "feature/new".
Tag the <release> for the <git> with "v1.0.0".

Git actions emit events for reactive workflows: GitCommit, GitPush, GitPull, GitCheckout, GitTag, GitClone.

Action Patterns

Extract-Process-Return

Common pattern for request handlers:

(createUser: User API) {
    (* Extract *)
    Extract the <user-data> from the <request: body>.

    (* Process — Validate binds a fresh result, it never rebinds its input *)
    Validate the <valid> for the <user-data>.
    Create the <user> with <user-data>.
    Store the <stored-user> into the <user-repository> with <user>.

    (* Return *)
    Return a <Created: status> with <stored-user>.
}

Extract-Emit Pattern

Pattern for event-driven updates:

(createOrder: Order API) {
    Extract the <order-data> from the <request: body>.
    Create the <order> with <order-data>.
    Store the <order> into the <order-repository>.

    (* Emit for other handlers *)
    Emit an <OrderCreated: event> with <order>.

    Return a <Created: status> with <order>.
}