Glossary
Adama has its own vocabulary. Some of these terms are borrowed from other systems (with Adama-specific meaning), and some are unique to this platform. This glossary is organized alphabetically so you can find what you need fast.
A
Asset
A file -- image, PDF, video, whatever -- attached to and stored with an Adama document. Referenced using the asset type. Can be uploaded, downloaded, and served through web handlers.
asset profilePicture;
@web get /avatar {
return { asset: profilePicture };
}
Related: Web Endpoints
Async Channel
A channel declared without a handler body, used in state machine code to request input from specific principals. This is how the document asks you for data, rather than waiting for you to send it. The document says "I need a response from Alice" and blocks until Alice responds.
message Response {
int value;
}
private principal player;
channel<Response> respond; // Incomplete/async channel
#waiting {
future<Response> f = respond.fetch(player);
Response r = f.await();
}
Related: Channels, State Machines
await
An operation that blocks execution until a future resolves. Used in state machines to wait for user input from async channels. The document is literally paused here -- no CPU, no resources consumed -- until the input arrives.
message Move {
int x;
int y;
}
private principal player;
channel<Move> moveChannel;
#waitForMove {
future<Move> f = moveChannel.fetch(player);
Move m = f.await(); // Blocks until player responds
}
Related: State Machines
B
Blocked
A document state where execution has paused waiting for external input (typically from an async channel fetch). A blocked document isn't consuming resources; it just sits there until the required input arrives. This is by design -- it's how Adama handles async workflows without polling.
// In tests, check blocked state with @blocked
test AsyncTest {
@step;
assert @blocked; // Document is waiting for input
}
Related: Testing
Bubble
A per-viewer computed value (formula) that incorporates @who to produce different results for different connected users. Bubbles are ephemeral -- they exist only in the context of a viewer connection. Each viewer gets their own version.
record Card {
public principal owner;
public string suit;
}
table<Card> deck;
bubble my_cards = iterate deck where owner == @who;
Each connected viewer sees their own my_cards containing only cards they own. Alice sees her cards; Bob sees his. Same formula, different results.
C
Channel
A named endpoint for receiving messages from connected clients. Channels are the "write" path into a document -- how clients send data in. They can be complete (with handler code) or incomplete (for async workflows).
message Say { string text; }
message Response { int value; }
record Msg {
public principal sender;
public string text;
}
table<Msg> _messages;
// Complete channel with handler
channel say(Say msg) {
_messages <- {sender: @who, text: msg.text};
}
// Incomplete channel for async
channel<Response> respond;
Related: Channels
Compile-Time Privacy
Adama's approach to privacy where visibility rules are checked and enforced by the compiler, not at runtime. If the compiler can prove that private data might leak through a public field, it rejects the code. Privacy bugs that can't reach production are the best kind.
Related: Privacy
Connection
A persistent WebSocket link between a client and an Adama document. Connections are established via the platform and controlled by the @connected handler.
private principal owner;
@connected {
return @who == owner; // Only owner can connect
}
Related: Channels
Constructor (@construct)
The event handler that runs when a document is first created. This is where you initialize state.
private principal owner;
private datetime created_at;
@construct {
owner = @who;
created_at = Time.datetime();
transition #initial;
}
#initial {
// Starting state
}
Related: Language Fundamentals
Cron
A scheduled task system built into Adama. Cron jobs execute at specified times (daily, hourly, or monthly) without external schedulers. The document wakes up, does its work, and goes back to sleep. No crontabs, no external services.
record LogEntry {
public int age;
}
table<LogEntry> _logs;
@cron daily_cleanup daily 03:00 {
(iterate _logs where age > 30).delete();
}
Related: Scheduled Tasks
D
Delta
An incremental change notification sent from an Adama document to connected clients. Instead of sending the entire document state on every change, Adama sends only what changed. This is what makes real-time sync practical -- you're not re-sending the whole world on every keystroke.
Related: How It Works
Document
The fundamental unit of state and computation in Adama. A document is an instance of a deployed space, identified by a unique key. Think of it as a tiny virtual machine that:
- Contains all state defined in the Adama code
- Runs all event handlers and state machine logic
- Maintains connections to subscribed clients
- Is an independent, isolated entity
# Create a document
adama document create --space my-game --key game-123
Related: What is Adama
Document Key
A unique identifier for a document within a space. Keys are strings that you choose when creating documents.
adama document create --space my-app --key user-alice-profile
Related: CLI Reference
Durable Execution
The ability of Adama state machines to survive server restarts and continue exactly where they left off. Document state, pending futures, and scheduled transitions are all persisted. If the server crashes at 3 AM while a document is blocked waiting for input, it comes back up and keeps waiting. No lost state.
Related: State Machines
Dynamic
A type that can hold arbitrary JSON-like data. Useful for interoperability with external systems or when you need to handle unstructured data that doesn't fit a specific message or record type.
dynamic data;
Related: Types
E
Enum
An enumerated type with a fixed set of named values. Enums support pattern matching in switch statements.
enum GameState { Waiting, Playing, Finished }
public GameState state = GameState::Waiting;
Related: Types
F
fetch
A channel method that requests input from a specific principal. Returns a future that resolves when the user responds. This is the mechanism by which a document can say "I need player 1 to make a move" and wait for it.
message Response {
int value;
}
private principal player;
channel<Response> ch;
#waiting {
future<Response> f = ch.fetch(player);
Response r = f.await();
}
Related: Channels, State Machines
Formula
A reactive computed value that automatically updates when its dependencies change. Formulas must be pure (no side effects). They're lazily evaluated and cached -- computed only when accessed, recomputed only when their inputs change.
public int x = 0;
public int y = 0;
public formula distance = Math.sqrt(x * x + y * y);
Related: Formulas
Function
A pure computation that cannot modify document state. Functions can be called from formulas because they're guaranteed side-effect free.
function add(int a, int b) -> int {
return a + b;
}
Related: Language Fundamentals
Future
A value representing an asynchronous operation that will eventually produce a result. Used with async channels. You get a future from fetch, and you await it in a state block.
message Response {
int value;
}
private principal player;
channel<Response> ch;
#waiting {
future<Response> f = ch.fetch(player);
}
Related: State Machines
G
Guard
A condition in a channel handler that determines whether to process or reject a message. Guards are just early returns, but they're such a common pattern they deserve a name.
message Move {
int x;
int y;
}
private principal currentPlayer;
channel move(Move m) {
if (@who != currentPlayer) {
return; // Guard: reject if not current player
}
// Process move
}
Related: Channels
H
Handler
Code that executes in response to an event. Includes event handlers (@connected, @disconnected, @construct) and channel handlers.
Related: Channels
I
Incomplete Channel
See Async Channel.
Index
A database-style index on table fields to speed up query performance. Put index on fields you filter with ==, and queries go from scanning every record to direct lookup.
record Player {
public string name;
index name;
}
Related: Tables and Queries
Invention
The automatic creation of a document when someone connects to a non-existent document key. Controlled by the invent policy in @static. Connect to a document that doesn't exist, and if the policy allows it, it springs into existence.
@static {
invent { return @who != @no_one; }
}
Related: Configuration Reference
iterate
A keyword that converts a table into a queryable list, enabling filtering, sorting, and aggregation. This is how you get data out of tables.
record Player {
public string status;
}
table<Player> players;
public formula active = iterate players where status == "active";
Related: Tables and Queries
L
Label
A type representing a reference to a state machine state. Used for dynamic transitions when you want to compute which state to go to.
label nextState = #playing;
#playing {
// State code
}
Related: State Machines
Lazy Evaluation
Adama formulas are computed only when accessed and cached until dependencies change. You can define a hundred formulas and only pay for the ones someone actually looks at.
Related: Formulas
M
Maybe
A type wrapper indicating a value may or may not be present. Adama's approach to null safety. Division returns maybe<T> because division by zero is possible; you have to handle the possibility that there's no value.
maybe<int> score = @maybe(100);
@construct {
if (score as s) {
// s is available as int
}
}
Related: Types
Message
A structured data type used for communication via channels. Messages define the shape of data clients send into a document.
message ChatMessage {
string text;
bool isPrivate;
}
channel send(ChatMessage msg) {
// Handle message
}
Related: Records and Messages
O
Open Channel
A channel that accepts messages without requiring a persistent connection. Useful for webhooks and fire-and-forget operations where you don't want the overhead of maintaining a WebSocket.
message Payload {
string data;
}
channel webhook(Payload p) open {
// Handle webhook
}
Related: Channels
P
Policy
A named boolean expression that determines data visibility. Used with use_policy modifier. Policies are evaluated per-viewer, and they determine what each connected user can see.
private principal owner;
policy is_owner {
return @who == owner;
}
use_policy<is_owner> int secret_data;
Related: Privacy
Principal
A type representing a user identity. Every connected user has a principal, accessed via @who. Principals are opaque -- you can compare them and store them, but you can't peek inside.
principal owner;
@construct {
owner = @who; // Store current user as owner
}
Procedure
A function that can modify document state. Unlike functions, procedures can't be called from formulas because they have side effects.
int score = 0;
procedure updateScore(int points) {
score += points; // Modifies state
}
Related: Language Fundamentals
Projection
A tailored view of document data sent to a specific viewer based on privacy rules. Each connected client receives their own projection -- their own version of reality, filtered by what they're allowed to see.
Related: Privacy
R
Reactive
Automatically updating in response to changes. Formulas and bubbles are reactive -- change a field they depend on, and they recompute automatically. You don't write update code; the runtime handles it.
Related: Formulas
Record
A structured data type with named fields. Records define the schema for table rows.
record Player {
public string name;
public int score;
}
Related: Records and Messages
require
A keyword in records that controls entire record visibility. If the required policy returns false for a viewer, the record doesn't just hide its fields -- it ceases to exist from that viewer's perspective.
record PrivateNote {
public principal note_owner;
policy is_owner { return @who == note_owner; }
require is_owner;
}
Related: Privacy
Result
A type representing an operation outcome that may succeed or fail. Common with service calls where things can go wrong over the network.
result<string> r = service.call(request);
if (r.failed()) {
int code = r.code();
}
RxHTML
Adama's reactive HTML templating system for building client-side UIs that automatically sync with document state. Write HTML with data bindings; the framework handles the delta application and DOM updates.
Related: RxHTML Section
S
Service
An external integration point for connecting Adama documents to third-party APIs and backend services. Services let documents reach out to the world -- send emails, call APIs, talk to databases.
message SendRequest {
string to;
string body;
}
message SendResponse {
bool success;
}
service Email {
class = "email";
method<SendRequest, SendResponse> send;
}
Related: Services
Short-Circuit Evaluation
Logical operators (&&, ||) stop evaluating as soon as the result is determined. && stops if left is false; || stops if left is true. This matters for guard patterns where the second condition would crash if the first condition isn't met.
Related: Operators Reference
Space
A named container for Adama code. When you deploy code to a space, all documents in that space run that code. Think of a space as an "application" or "project."
adama space create --name my-app
adama space deploy --name my-app --file main.a
Related: CLI Reference
State
A named block of code in a state machine. States are defined with # prefix and represent discrete phases of execution.
#playing {
// Code for the playing state
transition #scoring;
}
#scoring {
// Code for the scoring state
}
Related: State Machines
State Machine
A programming model where documents progress through defined states. Adama's state machines support async operations (awaiting user input), delayed transitions (do something in 60 seconds), and durable execution (survive server restarts).
Related: State Machines
T
Table
A collection of records with automatic ID management. Tables support insertions, queries, updates, and deletions. Each record gets an auto-incrementing id field.
record Player {
public string name;
public int score;
}
table<Player> players;
@construct {
players <- {name: "Alice", score: 0};
}
Related: Tables and Queries
Transition
A statement that moves the state machine from one state to another. Can be immediate or delayed.
#current {
transition #nextState;
}
#delayed {
transition #timeout in 60; // Delayed by 60 seconds
}
#nextState {
}
#timeout {
}
Related: State Machines
V
Viewer
The connected user currently observing the document. Accessed via @viewer in bubbles to read viewer state -- the preferences and filters that the client sends along with its connection.
record Item {
public string name;
}
table<Item> items;
view int pageNumber;
bubble page = iterate items offset @viewer.pageNumber * 10 limit 10;
Related: Formulas
Viewer State
Client-controlled variables sent with the connection that influence bubbles. This is how clients tell the server what they want to see -- pagination, filtering, sorting, etc.
view string filter;
view string sortField;
Related: Formulas
viewer_is
A privacy modifier that restricts field visibility to a specific principal stored in another field. Only the user whose identity matches the referenced field can see the data.
private principal owner;
viewer_is<owner> string privateNotes;
Related: Privacy
W
Web Handler
An HTTP endpoint defined in Adama code. Documents can handle REST requests, serve HTML, respond to webhooks -- all from within the document itself.
@web get /status {
return { json: { alive: true } };
}
Related: Web Endpoints
@who
The special constant representing the currently executing user's principal. Available in channels, policies, bubbles, and event handlers. If there's one @ constant you need to know, it's this one.
message Empty {}
private principal owner;
channel claim(Empty msg) {
owner = @who; // Current user becomes owner
}
Related: @ Constants Reference
Quick Reference
| Term | Brief Definition |
|---|---|
| Asset | Attached file |
| Bubble | Per-viewer formula |
| Channel | Message endpoint |
| Delta | Incremental update |
| Document | State instance |
| Formula | Reactive computed value |
| Message | Communication data type |
| Policy | Visibility rule |
| Principal | User identity |
| Procedure | State-modifying function |
| Record | Structured data type |
| Space | Code container |
| State | Machine phase |
| Table | Record collection |
| Transition | State change |