# Autolang

> An orchestration language designed from the ground up for AI to write correctly the first time - with strict host-governed capabilities.

Autolang is an AI-native orchestration language and deterministic virtual machine. It solves the production bottleneck of executing untrusted AI-generated code by enforcing safety at the language runtime layer rather than sandboxing full operating systems.

Host applications (in Node.js, TypeScript, or C++) expose discrete business capabilities. AI scripts orchestrate those capabilities under strict host authority, explicit memory quotas, and opcode instruction budgets.

## Core Architectural Pillars

- **Surface Match with Kotlin:** Adopts syntax patterns language models are already familiar with (`val`, `var`, `if/else`, `when`, `?.`, `arrayOf()`). A familiar surface reduces syntax drift - the compiler still validates every name, type, and capability before execution.
- **Intentional Scope:** Deliberately omits human-scale architectural constructs (interfaces, reflection, deep inheritance, coroutines). Restricting the grammar strictly to workflow control flow eliminates failure surfaces, prevents over-engineering, and minimizes syntax drift.

## 3-Layer Defense Model

1. **Compiler Layer (Static Validation & Diagnostics):** Enforces strict static type checking and symbol resolution before bytecode emission. Absorbs common syntax drift at the compiler boundary and emits structured diagnostics with available capabilities to assist autonomous model self-correction.
2. **Capability Layer (Host Authority & Default Deny):** The AI never receives database credentials, raw network sockets, or OS primitives. The host explicitly registers capabilities. AI scripts execute only registered functions under strict host validation.
3. **VM Layer (Deterministic Resource Bounding):** Executes bytecode inside a custom virtual machine bounded by opcode instruction limits and managed memory quotas. Runaway compute or excessive allocations terminate automatically, protecting host stability.

## Why Autolang Over Tool Calling

Tool calling is suitable for single, isolated external queries. When an agent must evaluate collections, process batch records, or execute multi-step business logic, sequential tool calling incurs compounding network latency, escalating token costs, and fragile retry chains.

With Autolang:
- The model generates the entire orchestration workflow once.
- The script compiles and executes locally inside the VM against host capabilities, in a single deterministic pass.
- Loops, intermediate variables, and conditional branching resolve deterministically without repeated LLM inference cycles.

## Quick Syntax Example

```kotlin
@import("inventory")
@import("notifications")

// AI script orchestrating host-registered capabilities
val items = inventory.listCurrentStock()
var restockCount = 0

items.filter {|item| item.quantity < 5}
    .forEach {|item|
        notifications.sendAlert("Ops", "Low stock for " + item.sku)
        restockCount += 1
    }

println("Items flagged for restock: " + restockCount)
```

## Host Integration Example (TypeScript / Node.js)

```typescript
import { ACompiler } from 'autolang-compiler';

const compiler = await ACompiler.create();

// Register host capability
compiler.registerBuiltInLibrary("notifications", `
    @native("sendAlert")
    fun sendAlert(channel: String, msg: String): Bool
`, { autoImport: true }, {
    sendAlert: (channel, msg) => alertService.dispatch(channel, msg)
});

await compiler.compileAndRun("workflow.atl", `
    @import("notifications")
    notifications.sendAlert("Ops", "Batch processing completed successfully")
`);
```

## Primary AI References & Documentation Links

- [Full Documentation for LLMs](https://autolang.vercel.app/llms-full.txt): Complete, concatenated documentation text for single-request ingestion.
- [AI Agent Language Reference](https://autolang.vercel.app/autolang-ai-reference.md): Complete, single-file reference manual designed for LLMs generating Autolang code.
- [Documentation Overview](https://autolang.vercel.app/docs): Introduction to Autolang concepts and runtime architecture.
- [Philosophy & Vision](https://autolang.vercel.app/docs/philosophy-vision): Why Autolang exists, capability boundaries, and where it sits relative to container isolation.
- [Syntax & Control Flow Guide](https://autolang.vercel.app/docs/language-guide/syntax): Variables, types, functions, control flow (`if`, `when`, `for`, `while`), and closures.
- [Classes & Inheritance](https://autolang.vercel.app/docs/language-guide/classes-inheritance): Primary constructors, access modifiers, extension functions, and index operator overloading.
- [Standard Library & Modules](https://autolang.vercel.app/docs/language-guide/standard-library): Array, Map, Set, String, Math, Date, and JSON modules.
- [Security Model & Sandbox](https://autolang.vercel.app/docs/security-model): Capability isolation, instruction budget caps, and host-managed memory governance.
- [System Architecture](https://autolang.vercel.app/docs/architecture): Virtual machine pipeline, bytecode compiler, and embedding host session lifecycle.
- [NPM Integration Guide](https://autolang.vercel.app/docs/integration-npm): Embedding Autolang VM into Node.js / TypeScript applications.
- [Native Libraries Guide](https://autolang.vercel.app/docs/integration-npm/native-libraries): Creating custom `@native` bindings and host function delegates.
- [Best Practices Guide](https://autolang.vercel.app/docs/integration-npm/best-practices): Design patterns for `@js_object`, capability scoping, memory limits, and common mistakes.
- [Interactive WebAssembly Playground](https://autolang.vercel.app/docs/editor): In-browser interactive compiler and VM runner.