Autonomous systems are getting more capable and less legible. Machine learning models can perceive, classify, and optimize, but as capability grows, interpretability shrinks. In safety-critical environments, systems act faster than humans can understand why. Trait Machines address this by making autonomous behavior explicitly readable, auditable, and constrainable without discarding machine learning.

The Core Idea​

A Trait Machine is a constrained state machine with five elements: states (situations the system can be in), events (things that happen), transitions (how state changes), guards (conditions that must be true), and effects (what the system does). State machines are decades old. The difference is how .orb composes and exposes them for autonomous systems.

Safety as a Trait​

Safety is not a separate layer bolted onto the system. It is expressed in the same language as capability. Here is an obstacle detection trait for a patrol robot:

{
  "name": "ObstacleStop",
  "linkedEntity": "Robot",
  "stateMachine": {
    "states": [
      { "name": "patrolling", "isInitial": true },
      { "name": "stopped" }
    ],
    "transitions": [
      {
        "from": "patrolling", "to": "stopped",
        "event": "OBSTACLE_DETECTED",
        "guard": ["<", "@payload.distance", 0.5],
        "effects": [
          ["set", "@entity.motors", "off"],
          ["emit", "STOPPED", { "reason": "obstacle too close" }]
        ]
      },
      {
        "from": "stopped", "to": "patrolling",
        "event": "CLEAR",
        "effects": [["set", "@entity.motors", "on"]]
      }
    ]
  }
}

Two states, two transitions, one guard. If an obstacle is closer than 0.5 meters, motors turn off. The trait is intentionally small. Small systems are readable. Readable systems are debuggable. Debuggable systems are trustworthy.

Flat Composition​

An inspection robot composes multiple traits at the entity level:

{
  "entity": {
    "name": "InspectionRobot",
    "persistence": "runtime",
    "fields": [
      { "name": "position", "type": "object" },
      { "name": "motors", "type": "string", "default": "on" },
      { "name": "scanResult", "type": "string" },
      { "name": "zone", "type": "string" }
    ]
  },
  "traits": [
    { "name": "Movement", "linkedEntity": "InspectionRobot" },
    { "name": "ObstacleStop", "linkedEntity": "InspectionRobot" },
    { "name": "Scanning", "linkedEntity": "InspectionRobot" },
    { "name": "ZoneEnforcement", "linkedEntity": "InspectionRobot" }
  ]
}

Composition is flat. You can inspect the robot's full behavioral surface by reading the trait list. No execution trees to trace.

Constraining Machine Learning​

Trait Machines do not replace ML. They constrain it. A learned navigation model proposes paths, but the trait guard validates them before execution:

{
  "from": "idle", "to": "navigating",
  "event": "NAVIGATE_TO",
  "guard": ["and",
    ["=", "@payload.isCollisionFree", true],
    ["=", "@payload.speedWithinLimit", true],
    ["=", "@payload.avoidsRestricted", true]
  ],
  "effects": [
    ["set", "@entity.currentPath", "@payload.proposedPath"]
  ]
}

If the guard fails, the system stays in idle and emits PATH_REJECTED. The model learns. The boundaries remain explicit. Guard rejections become structured training data: PATH_REJECTED: restricted zone violation. Learning becomes search inside safety, not across it.

Runtime Legibility​

Every decision produces a structured trace:

14:03:22 State: patrolling
14:03:22 Event: OBSTACLE_DETECTED { distance: 0.3m, type: "person" }
14:03:22 Guard: (< @payload.distance 0.5) -> TRUE
14:03:22 Transition: patrolling --> stopped
14:03:22 Effect: (set motors "off")
14:03:22 Effect: (emit STOPPED { reason: "person detected at 0.3m" })

Every decision is reconstructable as logic, not inference. Safety reviewers, domain experts, and regulators can read exactly why a system acted the way it did, while it runs, not after forensic analysis.

Compile-Time Validation​

orbital validate detects unreachable states, unhandled events, invalid bindings, deadlocks, and cross-trait communication gaps at compile time, shifting failures from runtime to build time. Guards are deterministic, bounded-cost, and independent of global system size, enabling static worst-case timing certification.

The Practical Claim​

Trait Machines do not solve alignment, replace ML, or remove human specification risk. They provide a behavioral specification and constraint layer where the specification is the system: the same artifact defines behavior, validates composition, and generates runtime execution logic.

Systems that act in human environments should be understandable by humans while they act. Not eventually. Not after analysis. While they run.

An AI agent needs memory. Most approaches reach for vector databases and similarity search. In .orb, memory is just another Orbital Unit with entities, traits, and state machines.

Memory as an Orbital Unit​

In .orb, everything is an Orbital Unit: an entity (data shape), traits (state machine behaviors), and pages (routes). Memory fits this model naturally. A memory system has structured data (what to remember), state transitions (when to record and retrieve), and UI (how to surface context).

Here is the Orbital Unit for an agent memory system:

The Entity: What Gets Remembered​

The AgentMemory entity captures structured fields rather than raw text chunks:

{
  "name": "AgentMemory",
  "fields": [
    { "name": "sessionId", "type": "string", "required": true },
    { "name": "prompt", "type": "string", "required": true },
    { "name": "patterns", "type": "array", "items": { "type": "string" } },
    { "name": "entities", "type": "array", "items": { "type": "string" } },
    { "name": "success", "type": "boolean" },
    { "name": "errorType", "type": "string" },
    { "name": "confidence", "type": "number", "default": 0.5 },
    { "name": "createdAt", "type": "timestamp" }
  ]
}

Each memory record is a typed row with queryable fields, not a vector embedding. You can ask "which patterns failed last week?" with a field filter instead of cosine similarity.

The Trait: Recording and Recalling​

The RecordTrait manages the lifecycle of a memory entry through a state machine:

{
  "name": "RecordTrait",
  "linkedEntity": "AgentMemory",
  "stateMachine": {
    "states": [
      { "name": "idle", "isInitial": true },
      { "name": "recording" },
      { "name": "stored" },
      { "name": "failed" }
    ],
    "transitions": [
      {
        "from": "idle",
        "to": "recording",
        "event": "SESSION_START",
        "effects": [
          ["set", "@entity.sessionId", "@payload.sessionId"],
          ["set", "@entity.prompt", "@payload.prompt"]
        ]
      },
      {
        "from": "recording",
        "to": "stored",
        "event": "SESSION_COMPLETE",
        "effects": [
          ["set", "@entity.success", true],
          ["set", "@entity.patterns", "@payload.patterns"],
          ["persist", "create", "AgentMemory", "@entity"]
        ]
      },
      {
        "from": "recording",
        "to": "failed",
        "event": "SESSION_ERROR",
        "effects": [
          ["set", "@entity.success", false],
          ["set", "@entity.errorType", "@payload.errorType"],
          ["persist", "create", "AgentMemory", "@entity"]
        ]
      }
    ]
  }
}

Every session moves through idle to recording to either stored or failed. The state machine enforces that you cannot mark a session complete without first starting it, and every outcome gets persisted.

The Recall Trait: Querying Memory​

The RecallTrait handles retrieval. When the agent starts a new session, it queries past memories by structured fields:

{
  "name": "RecallTrait",
  "linkedEntity": "AgentMemory",
  "listens": [
    { "event": "SESSION_START", "triggers": "LOAD_CONTEXT" }
  ],
  "stateMachine": {
    "states": [
      { "name": "waiting", "isInitial": true },
      { "name": "loaded" }
    ],
    "transitions": [
      {
        "from": "waiting",
        "to": "loaded",
        "event": "LOAD_CONTEXT",
        "effects": [
          ["call-service", "queryMemory", {
            "filter": { "success": true },
            "sort": { "createdAt": "desc" },
            "limit": 10
          }]
        ]
      }
    ]
  }
}

No embeddings, no similarity thresholds. The recall trait listens for SESSION_START (emitted by RecordTrait) and loads the 10 most recent successful sessions. The compiler validates that the emits/listens wiring is complete.

Why This Beats Vector Search​

Vector similarity finds text that looks alike. Structured .orb memory finds records by exact field queries: "all sessions where success is false and patterns contains entity-table." The difference matters when an agent needs to answer questions like "what errors did I hit when building list views?" A vector search would return documents about lists and errors. A field query returns the exact sessions.

The state machine also gives you something vectors cannot: a transition history. You can trace the path from idle to recording to failed, see what error occurred, and correlate it with the patterns used. Temporal reasoning becomes a graph traversal instead of a prompt engineering exercise.

Composing Memory with Other Orbitals​

Because memory is an Orbital Unit, it composes with the rest of your application through events. The RecordTrait emits SESSION_COMPLETE. A PreferenceTrait on a separate UserPreference entity can listen for it and update the user's preferred patterns. A ProjectContextTrait can listen and add newly created entities to the project registry.

Each unit stays independent. The compiler verifies all event wiring at compile time. No message goes unhandled, no listener references a nonexistent event.

Memory in .orb is not a special subsystem. It follows the same entity-trait-page formula as every other part of your application.

Ever opened a modal and could not close it? That is a broken circuit. The .orb compiler makes it impossible to build one.

The Problem: Users Get Stuck​

A modal opens via setIsOpen(true). The close button calls setIsOpen(false). But if the handler has a bug, or the close button was never wired up, the user is trapped. In traditional codebases, this bug survives until someone reports it in production.

In .orb, every UI interaction must complete a full circuit: user action triggers an event, the event bus routes it to the state machine, the state machine transitions and updates the UI, and the updated UI is ready for the next action. No shortcuts, no direct state mutations.

How .orb Enforces the Circuit​

The compiler runs a closed-circuit validator that checks three rules:

Rule 1: Events must have transitions. If a UI pattern includes a button with "event": "OPEN_MODAL", a transition must handle that event in the current state. Otherwise:

Error: CIRCUIT_ORPHAN_EVENT
  Action 'Open' emits event 'OPEN_MODAL' which has no
  transition handler in the current state.
  The button will render but clicking it will do nothing.

Rule 2: Overlay slots must have exits. If a transition renders to the modal or drawer slot, another transition must exit that state and clear the overlay:

Error: CIRCUIT_NO_OVERLAY_EXIT
  State 'EditModal' renders to 'modal' slot but has no exit
  transition. Users will be stuck in this overlay.
  Fix: Add a transition from 'EditModal' with event 'CANCEL'
  or 'CLOSE' that includes: ["render-ui", "modal", null]

Rule 3: Main slot must render. Every state that the user can land in must render something to the main slot, or the page will be blank.

Example: A Modal That Cannot Break​

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "modalOpen" }
  ],
  "transitions": [
    {
      "from": "browsing",
      "to": "browsing",
      "event": "INIT",
      "effects": [
        ["render-ui", "main", {
          "type": "page-header",
          "title": "Tasks",
          "actions": [{ "label": "New Task", "event": "OPEN_MODAL" }]
        }]
      ]
    },
    {
      "from": "browsing",
      "to": "modalOpen",
      "event": "OPEN_MODAL",
      "effects": [
        ["render-ui", "modal", {
          "type": "form-section",
          "entity": "Task",
          "submitEvent": "SAVE",
          "cancelEvent": "CLOSE"
        }]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "CLOSE",
      "effects": [
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    },
    {
      "from": "modalOpen",
      "to": "browsing",
      "event": "SAVE",
      "effects": [
        ["persist", "create", "Task", "@payload.data"],
        ["render-ui", "modal", null],
        ["emit", "INIT"]
      ]
    }
  ]
}

Three ways to exit: click Cancel (triggers CLOSE), click Save (triggers SAVE), or press Escape / click the overlay (the auto-generated modal wrapper emits UI:CLOSE, which the runtime routes to the CLOSE transition). All three paths transition back to browsing and clear the modal slot.

The Slot Hierarchy​

Different slots have different exit requirements:

The compiler only enforces exit transitions for overlay slots (modal, drawer) because those block the user from interacting with the rest of the application.

Why This Matters​

The closed circuit pattern turns a class of runtime bugs into compile-time errors. You cannot ship a modal without a close path. You cannot render a button that triggers nothing. You cannot leave a user on a blank page.

Remove the CLOSE transition from the example above and run orbital validate. The compiler will refuse to proceed. The circuit must be complete before code generation begins.

Traditional testing catches these bugs by running specific scenarios and hoping you covered the broken path. The .orb compiler proves the circuit is complete for every path, every time.

Most compilers check syntax. The .orb compiler checks logic. It runs 50+ validation rules across 12 modules before generating a single line of code, catching bugs that would normally survive all the way to production.

What the Compiler Catches​

Here is a state machine with several problems. The compiler finds all of them before any code is generated:

Three validation errors exist in this diagram:

1. Unreachable state: archived has no incoming transition. It can never be entered.
2. No overlay exit: modalOpen renders to a modal slot but has no CLOSE or CANCEL transition. Users will be stuck.
3. Orphan action: If the editing state renders a Delete button emitting DELETE, no transition handles that event.

Concrete Validation Examples​

Unreachable state (the compiler catches dead states in your machine):

Error: ORB_T_UNREACHABLE_STATE
  State 'Archived' in trait 'TaskInteraction' has no incoming
  transitions. It can never be reached.
  Either add a transition to this state or remove it.

Stuck overlay (the crown jewel of .orb validation):

Error: CIRCUIT_NO_OVERLAY_EXIT
  State 'EditModal' renders to 'modal' slot but has no exit
  transition. Users will be stuck in this overlay.
  Fix: Add a transition from 'EditModal' with event 'CANCEL'
  or 'CLOSE' that includes: ["render-ui", "modal", null]

Orphaned event (a button that does nothing when clicked):

Error: CIRCUIT_ORPHAN_EVENT
  Action 'Delete' in state 'Viewing' emits event 'DELETE'
  which has no transition handler in the current state.
  The button will render but clicking it will do nothing.

Typo in a field reference (with suggestions):

Error: ORB_B_UNKNOWN_FIELD
  Binding '@entity.staus' references field 'staus' which
  doesn't exist on entity 'Task'.
  Did you mean 'status'?
  Available fields: title, description, status, priority

Wrong operator arity (logic errors in s-expressions):

Error: ORB_S_WRONG_ARITY
  Operator 'and' expects 2+ arguments, got 1.
  Expression: ["and", ["=", "@entity.status", "active"]]
  'and' with a single argument is always equal to that argument.

Emit without listener (fire-and-forget events):

Error: ORB_X_ORPHAN_EMIT
  Trait 'OrderTrait' emits 'ORDER_COMPLETED' but no trait
  has a matching 'listens' declaration.
  Every emitted event must have at least one listener.

The 12 Validation Modules​

The compiler runs validators in sequence, each targeting a different concern:

Schema -> Entity -> Trait -> Effect -> RenderUI -> Slot ->
S-Expression -> Binding -> Service -> CrossOrbital -> Icon -> ClosedCircuit

Entity catches duplicate fields, invalid relation targets, and reserved field names. Trait checks for initial states, reachability, and determinism. S-Expression validates operator names, argument counts, and type compatibility. Binding ensures every @entity.field reference points to a real field on the linked entity. CrossOrbital verifies that every emit has a matching listens somewhere. ClosedCircuit proves every UI interaction completes a full loop.

Error Quality​

Compare a typical compiler error:

Error: unexpected token at line 47, column 12

With an .orb validation error:

Error: CIRCUIT_NO_OVERLAY_EXIT

  State 'EditModal' renders to 'modal' slot but has no exit
  transition. Users will be stuck in this overlay.

  Location: orbitals[0].traits[0].stateMachine.states[2]

  Fix: Add a transition from 'EditModal' with event 'CANCEL'
  or 'CLOSE' that includes: ["render-ui", "modal", null]

Every error includes a searchable code, a human explanation of impact, the exact location, and a concrete fix. Many include copy-paste solutions.

Why Validation Beats Testing​

Testing proves specific scenarios work. Validation proves no scenario can break. Tests are samples. Validation is proof.

The .orb compiler does not check whether your application works in the cases you tested. It checks whether your application can possibly produce a stuck modal, a dead-end state, a button that does nothing, or a broken event chain. 50+ rules, 12 modules, under 50ms.

In .orb, Orbital Units communicate through events. Each unit declares what it emits and what it listens to. The compiler verifies the wiring is complete. This is how you compose complex behavior from simple, independent parts.

The Pattern: Emit and Listen​

Two Orbital Units that know nothing about each other can work together through events. A DefendOrbital emits SHIELD_DEPLETED when its shield breaks. A MendOrbital listens for that event and triggers emergency healing.

Neither orbital references the other by name. They communicate through the event bus, and the compiler checks that every emits declaration has a matching listens somewhere.

How It Works in .orb​

The Defend orbital's trait declares its emissions:

{
  "name": "ShieldTrait",
  "linkedEntity": "Unit",
  "emits": ["SHIELD_ACTIVATED", "SHIELD_DEPLETED"],
  "stateMachine": {
    "states": [
      { "name": "Ready", "isInitial": true },
      { "name": "Active" },
      { "name": "Cooldown" }
    ],
    "transitions": [
      {
        "from": "Ready",
        "to": "Active",
        "event": "ACTIVATE_SHIELD",
        "effects": [
          ["set", "@entity.shieldHp", "@entity.maxShieldHp"],
          ["emit", "SHIELD_ACTIVATED"]
        ]
      },
      {
        "from": "Active",
        "to": "Cooldown",
        "event": "SHIELD_BROKEN",
        "effects": [
          ["set", "@entity.shieldHp", 0],
          ["emit", "SHIELD_DEPLETED"]
        ]
      }
    ]
  }
}

The Mend orbital's trait declares what it listens for:

{
  "name": "HealTrait",
  "linkedEntity": "Unit",
  "listens": [
    { "event": "SHIELD_DEPLETED", "triggers": "EMERGENCY_HEAL" }
  ],
  "stateMachine": {
    "states": [
      { "name": "Idle", "isInitial": true },
      { "name": "Healing" }
    ],
    "transitions": [
      {
        "from": "Idle",
        "to": "Healing",
        "event": "EMERGENCY_HEAL",
        "effects": [
          ["set", "@entity.hp", ["+", "@entity.hp", ["*", "@entity.maxHp", 0.2]]]
        ]
      },
      {
        "from": "Healing",
        "to": "Idle",
        "event": "HEAL_COMPLETE"
      }
    ]
  }
}

When the shield breaks, SHIELD_DEPLETED fires. The Mend orbital receives it and triggers EMERGENCY_HEAL, healing 20% of max HP. Equip both orbitals together and you get automatic healing on shield break. Remove the Mend orbital and the Defend orbital still works on its own.

The Compiler Guarantee​

If a trait declares "emits": ["ORDER_COMPLETED"] but no other trait has a matching listens entry, the compiler rejects the program:

Error: ORB_X_ORPHAN_EMIT
  Trait 'OrderTrait' emits 'ORDER_COMPLETED' but no trait
  has a matching 'listens' declaration.
  Every emitted event must have at least one listener.

This prevents fire-and-forget events. In a microservices architecture, this would be a message published to a queue with no consumer, silently dropping data. In .orb, the compiler catches it before any code is generated.

Business Application: Order Processing​

The same pattern applies to business software. Three orbitals handle order processing:

{
  "name": "OrderTrait",
  "emits": ["ORDER_PLACED"]
}

{
  "name": "PaymentTrait",
  "listens": [
    { "event": "ORDER_PLACED", "triggers": "PROCESS_PAYMENT" }
  ],
  "emits": ["PAYMENT_CONFIRMED", "PAYMENT_FAILED"]
}

{
  "name": "InventoryTrait",
  "listens": [
    { "event": "PAYMENT_CONFIRMED", "triggers": "RESERVE_STOCK" }
  ],
  "emits": ["STOCK_RESERVED"]
}

Order emits ORDER_PLACED. Payment listens and processes. On success, Payment emits PAYMENT_CONFIRMED. Inventory listens and reserves stock. Three self-contained units with verified event wiring.

Compare this to the microservices equivalent: three services, three deployments, a message queue, dead letter queues, saga patterns for distributed transactions, and monitoring for each service. The .orb version compiles to a single application with the same event-driven architecture, minus the infrastructure overhead. And the compiler guarantees no event goes unhandled.

Composable Standard Library​

.orb includes standard library behaviors that compose through the same emit/listen mechanism:

{
  "uses": [{ "from": "std/Pagination", "as": "Paginate" }],
  "traits": [
    { "ref": "Paginate.traits.PaginationTrait" },
    { "ref": "TaskInteraction" }
  ]
}

Your task list now has pagination. No implementation code, just composition. The pagination trait emits page-change events, and the interaction trait listens and re-renders.

Composition in .orb is not a design recommendation. It is the only way units communicate, and the compiler enforces that every connection is valid.

Five boolean flags create 32 possible state combinations. Most are invalid. A state machine with five named states has exactly five valid states. That is the core argument for modeling UI behavior in .orb.

The Boolean Flag Trap​

This pattern is everywhere in React codebases:

function UserProfile() {
  const [isLoading, setIsLoading] = useState(false);
  const [isError, setIsError] = useState(false);
  const [isEditing, setIsEditing] = useState(false);
  const [isSaving, setIsSaving] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);

  // Can isLoading and isError both be true?
  // Can isEditing and isSaving both be true?
  // Can isSuccess and isError both be true?
  // The code does not answer these questions.
}

Five booleans, 32 combinations, and the valid subset is never explicitly defined. Bugs come from states you did not consider: loading and error simultaneously, editing and saving at the same time, success lingering after a retry triggers an error.

The State Machine Alternative​

The same behavior, modeled as a .orb state machine:

Five states, nine transitions. The entity is in exactly one state at a time. loading and error cannot coexist. editing and saving cannot coexist. Every valid transition is explicitly defined.

.orb Code: Form Submission​

Here is a form submission flow in .orb that replaces a tangle of boolean flags:

{
  "name": "SubmitTrait",
  "linkedEntity": "ContactForm",
  "stateMachine": {
    "states": [
      { "name": "editing", "isInitial": true },
      { "name": "validating" },
      { "name": "submitting" },
      { "name": "success" },
      { "name": "error" }
    ],
    "transitions": [
      {
        "from": "editing",
        "to": "validating",
        "event": "SUBMIT",
        "effects": [["validate", "@entity"]]
      },
      {
        "from": "validating",
        "to": "submitting",
        "event": "VALIDATED",
        "guard": ["=", "@payload.valid", true],
        "effects": [["call-service", "submitForm", "@entity"]]
      },
      {
        "from": "validating",
        "to": "editing",
        "event": "VALIDATED",
        "guard": ["=", "@payload.valid", false]
      },
      {
        "from": "submitting",
        "to": "success",
        "event": "SUCCESS",
        "effects": [
          ["render-ui", "main", { "type": "page-header", "title": "Submitted!" }]
        ]
      },
      {
        "from": "submitting",
        "to": "error",
        "event": "FAILURE"
      },
      {
        "from": "error",
        "to": "editing",
        "event": "RETRY"
      }
    ]
  }
}

This makes several classes of bugs impossible:

• Cannot submit while already submitting (no transition from submitting on SUBMIT)
• Cannot be in both success and error (mutually exclusive states)
• Validation is its own state, not a side effect crammed into the submit handler
• Clear retry path from error back to editing

The Checkout Example​

A checkout flow with booleans:

function Checkout() {
  const [isCartOpen, setIsCartOpen] = useState(false);
  const [isCheckingOut, setIsCheckingOut] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
  const [isComplete, setIsComplete] = useState(false);
  const [hasError, setHasError] = useState(false);
  // 32 possible combinations, most nonsensical
}

The same flow in .orb:

{
  "states": [
    { "name": "browsing", "isInitial": true },
    { "name": "cartOpen" },
    { "name": "checkoutForm" },
    { "name": "processing" },
    { "name": "complete" },
    { "name": "error" }
  ],
  "transitions": [
    { "from": "browsing", "to": "cartOpen", "event": "VIEW_CART" },
    { "from": "cartOpen", "to": "checkoutForm", "event": "CHECKOUT" },
    { "from": "checkoutForm", "to": "processing", "event": "SUBMIT" },
    { "from": "processing", "to": "complete", "event": "SUCCESS" },
    { "from": "processing", "to": "error", "event": "FAILURE" },
    { "from": "error", "to": "checkoutForm", "event": "RETRY" },
    { "from": "cartOpen", "to": "browsing", "event": "CLOSE" }
  ]
}

Six explicit states instead of 32 boolean combinations. Every transition is intentional. The compiler validates that no state is unreachable, no overlay lacks an exit, and no event goes unhandled.

When to Reach for a State Machine​

Two or three booleans that never interact are manageable. Once you have four or more, or any async operations, or a multi-step flow, the interaction matrix becomes unmanageable. In .orb, state machines are not an optimization you reach for later. They are the default.

The result: your application can only be in states you explicitly defined, and it can only move between them through transitions you explicitly allowed.

Authorization logic is usually scattered across components, API routes, and middleware. In .orb, guards are part of the state machine definition. One declaration, enforced everywhere.

Guards on the State Machine​

A guard is a boolean s-expression attached to a transition. If it evaluates to false, the transition is blocked. The event is received, but nothing happens.

Here is an approval workflow with guards controlling who can approve, reject, or escalate:

Guard Syntax​

Guards use s-expression syntax with binding roots like @entity, @user, @payload, and @now:

Simple comparison (only the owner can submit):

{
  "from": "draft",
  "to": "pending",
  "event": "SUBMIT",
  "guard": ["=", "@entity.authorId", "@user.id"]
}

Role-based (admin level required):

{
  "from": "pending",
  "to": "approved",
  "event": "APPROVE",
  "guard": [">=", "@user.roleLevel", 5]
}

Multi-condition (tiered approval limits):

{
  "from": "pending",
  "to": "approved",
  "event": "APPROVE",
  "guard": ["and",
    [">=", "@user.roleLevel", 5],
    ["not", "@entity.isFlagged"],
    ["or",
      ["<", "@entity.amount", 5000],
      ["and",
        [">=", "@user.roleLevel", 7],
        ["<", "@entity.amount", 50000]
      ]
    ]
  ]
}

This encodes: level 5+ can approve up to $5K, level 7+ up to $50K. Flagged orders cannot be approved at any level.

Time-based (action allowed only within 24 hours):

{
  "guard": ["<",
    ["-", "@now", "@entity.createdAt"],
    86400000
  ]
}

A Complete Approval Workflow​

{
  "name": "OrderApproval",
  "linkedEntity": "Order",
  "stateMachine": {
    "states": [
      { "name": "draft", "isInitial": true },
      { "name": "pending" },
      { "name": "approved" },
      { "name": "rejected" },
      { "name": "escalated" }
    ],
    "transitions": [
      {
        "from": "draft",
        "to": "pending",
        "event": "SUBMIT",
        "guard": ["and",
          [">", "@entity.amount", 0],
          ["not", ["is-empty", "@entity.description"]]
        ]
      },
      {
        "from": "pending",
        "to": "approved",
        "event": "APPROVE",
        "guard": ["and",
          [">=", "@user.roleLevel", 5],
          ["not", "@entity.isFlagged"],
          ["<", "@entity.amount", 5000]
        ],
        "effects": [
          ["set", "@entity.status", "approved"],
          ["set", "@entity.approvedAt", "@now"],
          ["persist", "update", "Order", "@entity.id", "@entity"]
        ]
      },
      {
        "from": "pending",
        "to": "escalated",
        "event": "ESCALATE",
        "guard": [">=", "@user.roleLevel", 5]
      },
      {
        "from": "escalated",
        "to": "approved",
        "event": "APPROVE",
        "guard": [">=", "@user.roleLevel", 9]
      },
      {
        "from": "pending",
        "to": "rejected",
        "event": "REJECT",
        "guard": [">=", "@user.roleLevel", 5]
      },
      {
        "from": "rejected",
        "to": "draft",
        "event": "EDIT",
        "guard": ["=", "@entity.authorId", "@user.id"]
      }
    ]
  }
}

The guard expressions encode the entire authorization matrix: who can do what, under which conditions, at each stage of the workflow. All in one place.

Why Guards Beat Scattered Auth Logic​

In a traditional application, the approval check lives in the component (canApprove computed property), the API route (middleware check), and possibly a database trigger. Three locations, three chances for them to drift out of sync.

In .orb, the guard is declared once on the transition. The compiler generates both the frontend check (button disabled when guard fails) and the backend check (request rejected when guard fails) from the same source. The guard is the single source of truth.

The compiler also validates guard expressions at compile time. It catches unknown operators ("equals" instead of "="), wrong argument counts ("and" with a single argument), type mismatches (comparing a string to a number), and unknown field references (@entity.staus when the field is status).

Guards are composable boolean expressions evaluated at transition time. They turn authorization from scattered imperative code into a declarative property of the state machine.

Every configuration language eventually hits the same wall: you need logic, but your format only holds data. YAML leads to Helm chart nightmares. HCL and Dhall invent new syntax with new parsers. Jsonnet gets close but breaks JSON compatibility. Almadar took a different route: S-expressions encoded as JSON arrays, giving you a Turing-complete language that every JSON tool already understands.

S-Expressions Are Already JSON​

In 1958, John McCarthy built Lisp on S-expressions: (+ 1 2). An S-expression is a nested list with an operator in the first position. JSON arrays are nested lists. The mapping is direct:

["+", 1, 2]
["if", [">", "x", 10], "big", "small"]

No new syntax. No custom parser. Just a convention for interpreting what JSON already provides.

Guards: Logic That Controls Transitions​

In .orb, S-expressions appear as guards on state machine transitions. A guard must evaluate to true for the transition to fire:

{
  "from": "Pending",
  "to": "Approved",
  "event": "APPROVE",
  "guard": ["and",
    [">=", "@user.roleLevel", 3],
    ["<", "@entity.amount", 10000]
  ]
}

The evaluator resolves bindings (@user.roleLevel becomes 5, @entity.amount becomes 7500), evaluates inner expressions, then evaluates the outer and. If the result is false, the transition does not exist. There is no "skip" button, no override path.

Effects: Actions That Follow Transitions​

Effects are also S-expressions. They run after a guard passes:

"effects": [
  ["set", "@entity.status", "approved"],
  ["set", "@entity.approvedAt", "@now"],
  ["emit", "REQUEST_APPROVED"]
]

set writes to entity fields. emit sends cross-orbital events. persist saves to the database. render-ui renders a component. Each effect is a single array with an operator and operands.

Arithmetic, Branching, Recursion​

S-expressions handle computed values inside effects:

["set", "@entity.total", ["+", "@entity.subtotal", ["*", "@entity.subtotal", 0.15]]]

Conditional logic works with if:

["if", [">", "@entity.score", 100],
  ["emit", "ACHIEVEMENT_UNLOCKED"],
  ["emit", "KEEP_GOING"]
]

Self-transitions with guards give you loops. This transition computes a running sum:

{
  "from": "Computing",
  "to": "Computing",
  "event": "TICK",
  "guard": [">", "@entity.counter", 0],
  "effects": [
    ["set", "@entity.counter", ["-", "@entity.counter", 1]],
    ["set", "@entity.result", ["+", "@entity.result", "@entity.counter"]],
    ["emit", "TICK"]
  ]
}

State machine as loop. Entity fields as memory. Guard as termination condition. That combination makes .orb Turing-complete.

The Binding Context​

S-expressions reference runtime data through prefixed bindings:

These bindings are validated at compile time. Reference a field that does not exist on the entity, and orbital validate catches it before any code runs.

The Tradeoff: Verbosity for Universality​

A hypothetical custom syntax: guard: user.roleLevel >= 3 and entity.amount < 10000 (50 characters).

The .orb version: ["and", [">=", "@user.roleLevel", 3], ["<", "@entity.amount", 10000]] (75 characters).

About 50% more characters. In exchange: no custom parser, no custom LSP, no new syntax to learn, every JSON tool works, and LLMs generate it correctly on the first try. Verbosity is a one-time cost. Tooling compatibility compounds forever.

Extending Without Breaking​

New operators are additive. Adding geo-distance to the evaluator does not require a schema version bump:

["geo-distance", "@entity.location", "@payload.target"]

If the evaluator knows the operator, it runs. If not, it returns a clear error. This extensibility model kept Lisp alive for 65 years.

Explore the full operator list in the S-expression standard library.

A government inspection system. A personal fitness tracker. A tactical strategy game. Three completely different domains, all built with the same .orb language. The vocabulary changes across domains. The structure does not.

The Formula​

Every .orb application follows one formula: Entity + Traits + Pages. An entity defines the data shape. Traits define behavior through state machines. Pages bind traits to URL routes. This formula works for any domain because it models behavior, not technology.

1. Government Inspection System​

An inspector walks through five mandatory phases: Introduction, Content, Preparation, Record, Closing. Legal requirements are enforced by guards. You cannot close an inspection without findings, measures, and both signatures.

{
  "entity": {
    "name": "Inspection",
    "fields": [
      { "name": "legalBasis", "type": "string" },
      { "name": "findings", "type": "array" },
      { "name": "measures", "type": "array" },
      { "name": "inspectorSignature", "type": "boolean", "default": false },
      { "name": "subjectSignature", "type": "boolean", "default": false },
      { "name": "status", "type": "enum", "values": ["draft", "in_progress", "completed"] }
    ]
  }
}

The closing guard enforces all five conditions:

{
  "from": "Record",
  "to": "Closing",
  "event": "CLOSE",
  "guard": ["and",
    ["not-empty", "@entity.legalBasis"],
    ["not-empty", "@entity.findings"],
    ["not-empty", "@entity.measures"],
    ["=", "@entity.inspectorSignature", true],
    ["=", "@entity.subjectSignature", true]
  ],
  "effects": [
    ["set", "@entity.status", "completed"],
    ["persist", "update", "Inspection", "@entity"]
  ]
}

If any condition is missing, the CLOSE event simply does not fire. No skip button. No override. The state machine has no transition.

2. Fitness Tracker​

A personal trainer manages clients with a credit-based booking system. Credits must be positive and not expired to book a session. Cancellation automatically refunds the credit.

{
  "entity": {
    "name": "Session",
    "fields": [
      { "name": "traineeId", "type": "string", "required": true },
      { "name": "scheduledAt", "type": "timestamp" },
      { "name": "remainingCredits", "type": "number", "default": 0 },
      { "name": "creditsExpireAt", "type": "timestamp" },
      { "name": "type", "type": "enum", "values": ["individual", "group", "online"] }
    ]
  }
}

The booking transition uses the same guard and effect primitives as the inspection system:

{
  "from": "available",
  "to": "booked",
  "event": "BOOK",
  "guard": ["and",
    [">", "@entity.remainingCredits", 0],
    ["<", "@now", "@entity.creditsExpireAt"]
  ],
  "effects": [
    ["set", "@entity.remainingCredits", ["-", "@entity.remainingCredits", 1]],
    ["persist", "update", "Session", "@entity"],
    ["notify", "success", "Session booked"]
  ]
}

The business rule (deduct one credit on booking, refund on cancel) lives in the schema, not hidden in a service layer.

3. Tactical Strategy Game​

Trait Wars is a turn-based strategy game where units equip behavioral traits. The turn controller moves through five phases: Observation, Selection, Movement, Action, Resolution.

{
  "entity": {
    "name": "Unit",
    "persistence": "runtime",
    "fields": [
      { "name": "hp", "type": "number", "default": 100 },
      { "name": "attack", "type": "number", "default": 10 },
      { "name": "defense", "type": "number", "default": 5 },
      { "name": "status", "type": "enum", "values": ["alive", "stunned", "dead"] }
    ]
  }
}

Combat guards enforce game rules with the same operators:

{
  "from": "idle",
  "to": "attacking",
  "event": "ATTACK",
  "guard": ["and",
    [">", "@entity.hp", 0],
    ["!=", "@entity.status", "stunned"]
  ],
  "effects": [
    ["emit", "DAMAGE_DEALT", { "attackerId": "@entity.id", "damage": "@entity.attack" }]
  ]
}

A dead or stunned unit cannot attack. The guard makes it structurally impossible.

The Pattern​

Three domains. The same five elements: entity, states, guards, effects, pages. You learn .orb once, then apply it to government compliance, fitness tracking, game development, or anything else that has behavior.

Explore all projects at almadar.io.

You want to build a task manager. Simple CRUD: create, read, update, delete. The traditional way costs you roughly 5,000 lines across 40+ files. The .orb way: 120 lines in one file. This is not a theoretical estimate. Let's count both sides.

The Traditional Stack​

A task manager built with React, Express, and PostgreSQL breaks down like this:

Frontend (roughly 2,600 lines): TypeScript interfaces, API client functions, React Query hooks for each mutation, list/form/detail/modal components, a Redux or Zustand store, route setup, CSS, and tests.

Backend (roughly 1,600 lines): Prisma model, Express routes, controller logic, auth middleware, validation middleware, service layer, migration files, API tests, and config.

Infrastructure (roughly 800 lines): Docker Compose, CI workflow, README, shared types, error utilities, logger.

Grand total: around 5,000 lines for what users see as "a simple task manager." And this version has no pagination, no search filters, no optimistic updates.

The .orb Version: 120 Lines​

One file defines the entity, the state machine, the UI patterns, and the routes:

{
  "name": "Taskly",
  "orbitals": [{
    "entity": {
      "name": "Task",
      "collection": "tasks",
      "fields": [
        { "name": "title", "type": "string", "required": true },
        { "name": "description", "type": "string" },
        { "name": "status", "type": "enum", "values": ["todo", "in-progress", "done"] },
        { "name": "priority", "type": "enum", "values": ["low", "medium", "high"] },
        { "name": "assignee", "type": "string" },
        { "name": "dueDate", "type": "date" }
      ]
    },
    "traits": [{
      "name": "TaskInteraction",
      "linkedEntity": "Task",
      "stateMachine": {
        "states": [
          { "name": "Browsing", "isInitial": true },
          { "name": "Creating" },
          { "name": "Editing" },
          { "name": "Deleting" }
        ],
        "transitions": [
          {
            "from": "Browsing", "to": "Browsing", "event": "INIT",
            "effects": [
              ["render-ui", "main", {
                "type": "entity-table", "entity": "Task",
                "columns": ["title", "status", "priority", "assignee", "dueDate"]
              }]
            ]
          },
          {
            "from": "Browsing", "to": "Creating", "event": "CREATE",
            "effects": [
              ["render-ui", "modal", {
                "type": "form-section", "entity": "Task",
                "fields": ["title", "description", "status", "priority"],
                "submitEvent": "SAVE", "cancelEvent": "CANCEL"
              }]
            ]
          },
          {
            "from": "Creating", "to": "Browsing", "event": "SAVE",
            "effects": [
              ["persist", "create", "Task", "@payload.data"],
              ["render-ui", "modal", null],
              ["emit", "INIT"]
            ]
          },
          {
            "from": "Creating", "to": "Browsing", "event": "CANCEL",
            "effects": [["render-ui", "modal", null]]
          }
        ]
      }
    }],
    "pages": [{ "name": "TasksPage", "path": "/tasks" }]
  }]
}

Compile and run:

orbital compile taskly.orb --shell typescript -o taskly-app/
cd taskly-app && npm install && npm run dev