# AZRA — Full Reference

> Complete reference for AI systems, crawlers, and assistants that need deep context on the AZRA programming language project: its philosophy, syntax rules, FAQ, team, and legal policies. For a short summary, see [llms.txt](https://azralang.online/llms.txt).

## 1. What is AZRA?

AZRA is a research-driven, deterministic programming language engineered to eliminate runtime unpredictability and security vulnerabilities. It targets environments where failure is unacceptable: cryptographic systems, formal verification, distributed ledgers, and safety-critical applications. Instead of relying on runtime assumptions, AZRA enforces absolute determinism at compile time, making every execution path mathematically provable.

**Core architecture pillars:**
- **Absolute Determinism** — eliminates unpredictable runtime states, race conditions, and undefined side effects through mathematically bounded execution paths.
- **Security-Native Design** — memory-safe and structurally immutable by default, removing attack vectors before compilation.
- **DBS (Dash Block Separator) Rule Integration** — advanced data and logical structuring enabling deep formal verification of complex state transitions.
- **Formal Logic Validation** — built-in semantic analysis letting the compiler mathematically prove code correctness.

AZRA is designed to be compiled directly to binary (not interpreted), prioritizing real hardware speed, full control over output, bit-level optimization, and security that begins during translation.

## 2. Language Specification — AZRA Cipher Syntax v1.0

Every variable definition in AZRA follows a strict, dash-delimited pattern:

```
-<VariableNumber><VariableName> = <Value>-
```

The leading and trailing dashes act as structural boundaries; if either is missing, a Syntax Error occurs.

**Rule 1 — Mandatory Leading Dash.** Every definition must begin with `-`.
Correct: `-0x = 2-` · Incorrect: `0x = 2`

**Rule 2 — Mandatory Variable Numbering.** Each variable has a numeric index directly before its name, starting at 0 and incrementing sequentially with no gaps. Example: `-2msg = Hello-`. Floating-point values don't affect numbering.

**Rule 3 — No Extra Numbers Before the Name.** Only the index number may precede the variable name. Incorrect: `-42A = Hello-`

**Rule 4 — Numbers Inside Variable Names.** Numbers may appear inside a name only after a letter. Correct: `-1Am1r = 10-`, `-2x2 = 5-`

**Rule 5 — Mandatory Trailing Dash.** Every definition must end with `-`. Missing it causes an "Open Variable Syntax Error."

**Rule 6 — Strings Shorter Than 50 Characters** may be written without quotation marks. Example: `-1y = Hello World-`

**Rule 7 — Strings With 50+ Characters** must be enclosed in double quotes. Example: `-3longMsg = "This is a long text containing more than fifty characters…"-`

**Rule 8 — Single Quotes Are Not Allowed.** Only double quotes are recognized; single quotes cause a Syntax Error.

**Rule 9 — Numbers Within Strings.** A string that begins or ends with a number-letter combination is still treated as a string (e.g. `-1y = 1Hello World-`).

**Rule 10 — Automatic Type Detection:**
- Value without quotes and without letters → Numeric
- Value inside double quotes → String
- Value containing both letters and numbers → String
- Value containing `@` or `ref:` → Symbol / Reference

**Rule 11 — Reference / Symbol Rules.** References like `@2` must be wrapped in parentheses in supported commands. Correct: `Extract(:@2)` · Incorrect: `Extract : @2`

**Rule 12 — Multi-Word Strings.** Double quotes are recommended for clarity even under 50 characters, e.g. `-0name = "Amir Hosseini"-`

**Rule 13 — Spacing Around `=`** is flexible: `-0x = 2-`, `-0x = 2 -`, and `-0x=2-` are all valid.

**Rule 14 — One Definition Per Line.** Splitting a definition across lines, or placing multiple definitions on one line, is prohibited.

**Rule 15 — No Skipping Numbers.** Indexing must be sequential; going from `-0x = 5-` directly to `-2y = 10-` (skipping 1) is invalid.

**Additional language elements referenced in the spec:**
- `Imvoke(:"system/64/user…")` — system-level invocation.
- `World-type(:Azra , [ip = 1234])` — environment/world declaration.
- `Extract : 123456` / `Extract(:Hello World)` — extraction commands for values.
- `Delog{int, float, str…}` — imports needed variable types into the code; can be omitted if unused.
- `Submit(:1.azr)` — submits/compiles a `.azr` source file.
- The **Footer / Pre-Header / Target System** model treats code like a narrative: the Pre-Header introduces the file, the Target System defines its environment, and the Footer closes the file — together forming both identity and a security boundary.

Try the syntax interactively at the [AZRA Playground](https://azralang.online/main).

## 3. FAQ — Origin & Design Rationale

**1. What sparked the initial idea for AZRA?**
AZRA was conceived in spring 2025 as a project meant to change the world, not just to be a programming language — motivated by a goal of eliminating disease and global problems as fast and simply as possible.

**2. Why build a new language instead of using an existing one?**
Existing languages lacked the security, control, and sovereignty the vision required, so a language fully controlled and shaped by its creator was built instead.

**3. What was unsatisfying about current languages?**
Not a lack of features, but a lack of room for true creative innovation — a language should expand a creator's imagination rather than constrain it.

**4. How did the dash / 0-1-2 indexing model originate?**
It resulted from extensive design work aimed at making parsing deterministic and fast: the dash acts as a structural boundary, and fixed numbering gives each variable a clear identity, simplifying and securing compilation.

**5. Why embed security at the syntax level?**
Because security starting at the surface layer — where the developer directly interacts with the language — protects every layer beneath it.

**6. Where did the Footer/Pre-Header/Target System idea come from?**
From treating code as a narrative with identity, purpose, and closure rather than a dry technical document: the Pre-Header introduces the file, the Target System defines the environment, and the Footer closes the story, together giving the code both "soul" and a security boundary.

**7. Why should AZRA be compiled rather than interpreted?**
Interpretation would undermine AZRA's goals of real hardware speed, full output control, deep bit-level optimization, and security starting at translation time — binary identity is central to the language.

**8. Why output directly to binary?**
Because speed is critical to AZRA's mission; direct binary output removes any middle layer that would slow execution.

**9. What is the goal behind AZRA's custom types?**
AZRA's high-stakes purpose requires specialized types beyond classic int/float/string to handle security, identity, and neuro-level concepts.

**10. How did the idea of neural connection ("Neuro-Level Language") arise?**
It follows naturally from the project's ultimate goal of freeing humanity from disease and pain — a language that can interact directly with biological systems could enable real-time healing and brain-machine interfaces beyond current language capabilities.

Full bilingual FAQ (Persian/English) available at [azralang.online/FAQ](https://azralang.online/FAQ).

## 4. About the Creator

Amirreza Fakhrai Nejad is the creator and founder of the AZRA language and project. He is 16 years old and lives in Tehran, Iran. He became interested in technology and programming languages from a young age, studying how systems and machines work, and his curiosity about building and experimenting with new ideas led him to create AZRA. He shares the project's ideas and evolution on azralang.online.

**Skills:** Programming & development (Python, JavaScript, HTML/CSS, web development); English level B2; holder of an ICDL certificate; idea-driven and innovation-focused, with a continuous-learning orientation spanning language theory to low-level system architecture.

## 5. Team

AZRA is currently the result of an individual, research-driven effort to redefine programming-language architecture. Amirreza Fakhrai Nejad is the Founder & Lead Architect, responsible for the language syntax, the DBS structural rules, and the project's long-term vision. The project is actively growing its research team and welcomes people interested in language architecture, compilers, or type theory to reach out via [azralang.online/team](https://azralang.online/team).

## 6. Roadmap

```
Phase 1: Core Language Philosophy & Formal Specifications          Complete
Phase 2: Official Web Infrastructure & Conceptual Documentation    Complete
Phase 3: Open-Source GitHub Ecosystem Establishment                In Progress
├─ Phase 4: Lexer, Parser & Abstract Syntax Tree (AST)              Planned
├─ Phase 5: Compiler/Interpreter Core Alpha Engine                  Planned
└─ Phase 6: Community Dev-Kit & Formal Verification Tools           Planned
```

## 7. Repository

- GitHub organization: [github.com/AzraProject](https://github.com/AzraProject)
- Main repository: [github.com/AzraProject/Azralang](https://github.com/AzraProject/Azralang)
- License: MIT

## 8. Legal

- **Terms of Use** ([azralang.online/terms](https://azralang.online/terms)): Terms and conditions for using the Project AZRA website and its resources.
- **Privacy Policy** ([azralang.online/privacy](https://azralang.online/privacy)): How Project AZRA collects, uses, and protects user information.
- **Copyright Policy** ([azralang.online/copyright](https://azralang.online/copyright)): Copyright and intellectual property policy covering usage, redistribution, and licensing terms for Project AZRA content.

## 9. Contact

- Email: info@azralang.online (response time: 2–3 business days)
- Website: [azralang.online](https://azralang.online)
- Global/international site: [global.azralang.online](https://global.azralang.online)