فيزياء البرمجيات — The Physics of Software

Just as physics lets us predict how the physical world behaves, Orb lets us predict how software systems behave.

Orb (المدار) is a world modeling language — a semantic layer above programming languages that describes how systems work, not just what they do. Write a formal world model once, and AI agents generate valid implementations, the compiler validates correctness deterministically, and you can observe every possible state before a single line of code runs.

World Model (.orb) → Compiler → Valid System
        ▲                              │
        │                              ▼
   Natural Language              Observable
   (Human or AI)                 Behavior

Built for the AI age: Token-efficient representations that agents can generate and reason about. Deterministic validation that catches errors before runtime. Observable state spaces that let you prove correctness.

# Install CLI globally
npm install -g @almadar/orb

# Create a new project
orb new my-app
cd my-app

# Install dependencies
npm install

# Start development server
orb dev

Traditional programming languages tell computers what to do. Orb describes how things work:

• Entities — What exists in your system (User, Order, Task)
• Traits — How those things behave and change over time
• Pages — How the world is observed and interacted with

This world model is a formal specification that both humans and AI can reason about.

World Unit = Entity + Traits + Pages
System     = Σ(World Units)

Each orbital is a self-contained world model describing a domain of your system. Compose them to build complex, observable applications.

Because Orb models behavior formally, you can:

• Validate deterministically — The compiler proves your model is valid before runtime
• Exhaustively test — Examine all possible states to ensure correctness
• Generate efficiently — AI agents produce valid systems from natural language
• Reason precisely — Both humans and machines understand the same model

Every interaction flows through a predictable path:

User Action → Event → State Machine → Effects → World Update → (loop)

No hidden state mutations. No side effects you can't trace. Observable causality throughout.

Natural Language ──┐
(Human or AI)      │
                   │
Human-written ─────┼──► ┌─────────────────┐
.orb Schema        │    │  Builder IDE    │  Generates/Edits
                   │    │  (LLM Agent)    │  .orb schema
                   └──► └────────┬────────┘
                                  │
                                  ▼
                         ┌─────────────────┐
                         │ Rust Compiler   │  Parse → Validate → Resolve → Generate
                         │ (orbital-rust)  │
                         └────────┬────────┘
                                  │
                             ┌────┴────┐
                             ▼         ▼
                          TypeScript  Python
                             Shell     Shell
                          
                          (Rust shell coming soon)

Traditional code generation produces brittle outputs that break when requirements change. Orb's world models are token-efficient and structurally valid — AI agents can generate, modify, and reason about them reliably.

Deterministic validation catches errors at compile time, not runtime. Exhaustive state space analysis lets you prove your system behaves correctly before deploying.

State machines make causality explicit. Every effect traces back to an event. Every guard is visible. The system's behavior is inspectable and predictable.

Encode business logic, compliance requirements, or game mechanics in a formal model that can be validated, tested, and reasoned about — not buried in imperative code.

Define your data models:

{
  "entity": {
    "name": "Task",
    "collection": "tasks",
    "fields": [
      { "name": "id", "type": "string", "primaryKey": true },
      { "name": "title", "type": "string", "required": true },
      { "name": "status", "type": "enum", "values": ["pending", "done"] }
    ]
  }
}

📚 Entity Documentation

Define behavior with states, events, and transitions:

{
  "trait": {
    "name": "TaskBrowser",
    "linkedEntity": "Task",
    "stateMachine": {
      "states": [
        { "name": "Browsing", "isInitial": true },
        { "name": "Creating" }
      ],
      "events": ["INIT", "CREATE", "SAVE", "CANCEL"],
      "transitions": [
        {
          "from": "Browsing",
          "to": "Browsing",
          "event": "INIT",
          "effects": [
            ["render-ui", "main", { "type": "entity-table", "entity": "Task" }]
          ]
        }
      ]
    }
  }
}

📚 Trait Documentation | Closed Circuit

Patterns bridge schemas to UI components:

["render-ui", "main", {
  "type": "entity-table",
  "entity": "Task",
  "columns": ["title", "status"]
}]

📚 Patterns Documentation

Reuse pre-built behaviors:

{
  "uses": [{ "from": "std/behaviors/crud", "as": "CRUD" }],
  "traits": [{ "name": "TaskCRUD", "uses": ["CRUD"] }]
}

📚 Standard Library

# npm (recommended)
npm install -g @almadar/orb

# Or use npx
npx @almadar/orb validate schema.orb

# macOS/Linux
curl -fsSL https://orb.almadar.io/install.sh | sh

# Windows PowerShell
irm https://orb.almadar.io/install.ps1 | iex

# Homebrew
brew install almadar-io/tap/orb

# Core packages
npm install @almadar/core @almadar/validation @almadar/evaluator

# Standard library and operators
npm install @almadar/std @almadar/operators

# UI patterns and components
npm install @almadar/patterns @almadar/ui

# Runtime
npm install @almadar/runtime

The Orb language ecosystem is published to npm.

When something breaks, follow this order:

1. Fix schema first — 99% of issues are schema problems
2. Update shell components — Component bugs
3. Modify compiler — LAST RESORT (ask first!)

1. Edit Schema (.orb)
        ↓
2. Validate: orb validate schema.orb
        ↓
3. Compile: orb compile schema.orb --shell typescript
        ↓
4. Test generated code
        ↓
5. Iterate

📚 Developer Guide

Full documentation is available at orb.almadar.io/docs:

Visit orb.almadar.io/docs for complete documentation.

This repository also contains the orb.almadar.io documentation website, built with Docusaurus.

npm install
npm start          # Start dev server on port 3000
npm run build      # Production build
npm run serve      # Serve production build locally

• Discord
• GitHub Discussions
• LinkedIn

See CONTRIBUTING.md for guidelines.

BSL 1.1 (Business Source License). Converts to Apache 2.0 on 2030-02-01. Non-production use is free.

Built with ❤️ by Almadar