Roma4D_Core / Documentation Vault
These documents belong to the sealed Roma4D_Core subsystem.
“If you are reading this, YOUR SECURITY CLEARANCE DID NOT PASS, and you currently are not reading this page.”
RomanAILabs — Documentation/`. |
| `r4d sketch.r4d` [args…] | **Shorthand for `r4d run`** (same Expert / `--strict` rules). |
| `r4 run [--strict] file.r4d [-bench] [args…]` | Temp dir build, run executable. |
| `r4 build [--strict] file.r4d [-o out] [-bench]` | Emit persistent executable. |
**`--strict`:** Disables the **Native AI Expert** (no rich debug block, no interactive session); raw compiler/linker errors only. Use in CI. **`--forgiving`** (default) re-enables Expert after **`--strict`** if both appear — **later flag wins**.
**`-bench`:** Prints phase timings (`load_manifest`, `parse`, `typecheck`, LLVM, `zig_*` or `clang_*`, and `native_run` for `run`).
##### Package root resolution (`findPkgRoot`)
Order of resolution:
1. Walk **upward** from the **source file’s directory** until **`roma4d.toml`** is found.
2. If not found, try **`R4D_PKG_ROOT`**, then **`ROMA4D_HOME`** (must contain `roma4d.toml`).
3. If still not found, use **`EmbeddedPkgRoot`** (set at **link time** when built via `install.ps1`, `install.sh`, or `scripts/Install-R4dUserEnvironment.ps1` with `-ldflags -X .../cli.EmbeddedPkgRoot=...`).
This is how **`r4d C:\Desktop\foo.r4d`** works **without** `cd` into the clone after a proper install.
##### Relative paths and cwd
- **`r4 run demos\foo.r4d`** resolves **`demos\foo.r4d`** relative to the **shell current working directory**, not relative to `R4D_PKG_ROOT`.
- **Imports** (`from libgeo import ...`) resolve under **package root**, not next to the sketch file.
##### Windows PowerShell
Do **not** paste the **`PS C:\...>`** prompt into the terminal; on some systems **`PS`** is an alias and breaks the line.
##### Expert mode (forgiving, default)
On **`.r4d` build/run failure**, the CLI invokes the **Native AI Expert** (`src/ai/expert.go`): a **copy-pasteable terminal debug block**, **`debug/last_build_failure.log`** append, optional **patch suggestion + [y/N] prompt**, and an **interactive** Q&A when **stdin is a TTY**. Full behavior is specified in **§29**.
---
#### 4. Modules and imports
##### 4.1 Module file resolution
For `import foo.bar` or `from foo.bar import x`, the driver tries paths under **package root** (see `ResolveRoma4DModuleFile` in `src/compiler/source_ext.go`):
**Per segment / dotted name, extension order is always:** **`.r4d` → `.r4s` → `.roma4d`**.
Examples (conceptual):
- `pkgRoot/foo/bar.r4d` (or `.r4s` / `.roma4d`)
- `pkgRoot/foo.bar.r4d` (dotted flat file)
Missing file → **`ImportError`**.
##### 4.2 Import forms
| Form | Supported |
|------|-----------|
| `import mod` | Yes (with optional `as`). |
| `from mod import a, b, c` | Yes. |
| `from mod import *` | **No** — hard error in typechecker. |
##### 4.3 Exports (v0 behavior)
Importable names are **top-level** **`def`** and **`class`** in the module file. Prefer defining public APIs at module scope.
##### 4.4 Example library (`libgeo.r4d`)
```roma4d
def bump(n: int) -> int:
return n + 1
def identity_v4(v: vec4) -> vec4:
return v
```
Consumer:
```roma4d
from libgeo import bump, identity_v4
```
---
#### 5. Entry point, functions, and control flow
##### 5.1 `main`
- Entry point is **`def main()`** (no `if __name__ == "__main__"`).
- **`def main() -> int:`** must **`return`** an integer on all paths (otherwise **synthesized return** warning).
- **`def main() -> None:`** may use **`return None`**, bare **`return`**, or fall off the end; lowering targets **void** `main` in LLVM.
##### 5.2 Function definitions
- Use **`def name(args) -> ReturnType:`** with **annotated** parameters and return for public / non-trivial functions.
- **Variadic** Python features beyond what examples use: **avoid** unless you have verified with `r4d --strict`.
##### 5.3 Statements (supported idioms)
Use **indentation-based** blocks (spaces; keep consistent—**do not mix tabs**).
| Construct | Roma4D use |
|-----------|------------|
| `if` / `elif` / `else` | Yes. |
| `while` | Yes. |
| `for x in iterable:` | Yes; **`range(...)`** is the common iterable. |
| `break` / `continue` | Parsed; use like Python when needed. |
| `pass` | Yes (including inside **`spacetime:`**). |
| `return` | Yes. |
| `try` / `except` / `finally` | Lexed; **do not rely** for LLM-generated code—prefer compile-time clean code. |
| `async` / `await` | Lexed; **not** a supported async runtime model—**do not generate**. |
| `lambda` | Parsed; typechecking is **not** a first-class Python lambda story—**do not generate**; use **`def`**. |
| `match` / `case` | Lexed; **avoid** unless you verify. |
---
#### 6. Lexical structure: tokens, keywords, literals
##### 6.1 Comments and docstrings
- **`#` line comments** anywhere.
- **Triple-quoted strings** used as **class docstrings** appear in sources (e.g. `hello_4d.r4d`); treat as documentation only.
##### 6.2 Identifiers
Standard Python-like identifiers.
##### 6.3 Numeric literals
- **Integers** and **floats** as in Python.
- **Underscore separators** allowed: **`1_000_000`** (see demos).
##### 6.4 String literals
- **`"..."` and `'...'`** only.
- **No f-strings** (`f"..."`) — **not** the string model.
- **No** automatic formatting of **`int` / `float`** for human display in portable Roma4D—use **fixed messages** (`print("tick 512")`).
##### 6.5 Keywords (representative set)
Includes Python keywords **plus** Roma4D extensions:
**Roma4D-specific (non-negotiable spelling):** `par`, `soa`, `aos`, `vec4`, `rotor`, `multivector`, `borrow`, `mutborrow`, `unsafe`, **`t`** (time coordinate), **`spacetime`**.
**Also reserved / lexed as keywords:** `def`, `class`, `return`, `if`, `else`, `elif`, `for`, `while`, `pass`, `break`, `continue`, `import`, `from`, `as`, `True`, `False`, `None`, `and`, `or`, `not`, `in`, `is`, `try`, `except`, `raise`, `with`, `async`, `await`, `lambda`, `match`, `case`, …
**LLM rule:** If unsure whether a Python keyword works end-to-end, **do not use it**—stick to constructs in **`examples/hello_4d.r4d`**.
---
#### 7. Types (complete table)
##### 7.1 Host / scalar types
| Type | Notes |
|------|------|
| `int` | Signed integer. |
| `float` | Double-precision float in native lowering. |
| `str` | String; **`print`** is oriented toward **string** arguments in the Roma4D runtime. |
| `bool` | `True` / `False`. |
| `none` | Type of **`None`**; also used where no value is returned. |
##### 7.2 4D / systems types
| Type | Role |
|------|------|
| `vec4` | 4-component vector; geometric ops with `rotor` / `multivector`. |
| `rotor` | Rotor value; construct with **`rotor(angle=..., plane="...")`**. |
| `multivector` | General multivector; **`multivector()`** default ctor in examples. |
| `rawptr` | Raw pointer for `unsafe` + **`mir_*`**. |
| `time` | Type of **`t`** and time-coordinate reasoning. |
##### 7.3 Constructors / generics in surface syntax
- **`list[T]`** — e.g. **`list[vec4]`**, **`list[int]`**.
- **Do not** use C/Rust array syntax like **`[T; N]`** for bulk data.
---
#### 8. Builtins and constructors (authoritative)
Defined in **`seedBuiltins`** (`src/compiler/typechecker.go`). Names are **case-sensitive**.
| Name | Callable shape | Result (declared) | Notes |
|------|----------------|-------------------|-------|
| `print` | variadic | `none` | Runtime **`puts`** style—stick to **string literals** for portable code. |
| `range` | variadic | `list[int]`-like iterable | Used in **`for i in range(n):`** and comprehensions. |
| `len` | `(any)` | `int` | |
| `int`, `float`, `str`, `bool` | variadic ctor/cast | respective scalar type | |
| `abs` | `(any)` | `any` (loose) | Prefer for numerics only when needed. |
| `vec4` | keyword args | `vec4` | e.g. **`vec4(x=0, y=0, z=0, w=1)`** or **`w=1.0`**. |
| `rotor` | keyword args | `rotor` | **`rotor(angle=float, plane=str)`** — demos use **`"xy"`**, **`"yz"`**, **`"xw"`**. |
| `multivector` | variadic | `multivector` | Often **`multivector()`** empty. |
| `borrow` | `(x)` | `any` | **Argument must be a simple name** for borrow bookkeeping. |
| `mutborrow` | `(x)` | `any` | Same restriction pattern. |
| `timetravel_borrow` | `(x)` | `any` | Used in **`spacetime:`** regions in demos. |
| `mir_alloc` | `(size: int)` | `rawptr` | |
| `mir_ptr_store` | `(ptr: rawptr, value: int)` | `none` | |
| `mir_ptr_load` | `(ptr: rawptr)` | `int` | |
| `ollama_demo` | `()` | `int` | See §17. |
| `quantum_server_demo` | `()` | `int` | See §17. |
| `True`, `False`, `None` | literals | `bool` / `none` | |
**There is no** `time()`, **`datetime`**, **`random`**, **`open()`**, **`requests`**, **`numpy`**, **`torch`**.
---
#### 9. Geometric algebra (Cl(4,0)) operators
On **`vec4`**, **`rotor`**, **`multivector`** (where implemented), these operators are **geometric**:
| Operator | On 4D types | On plain `int` |
|----------|-------------|----------------|
| `*` | Geometric product (e.g. **`vec4 * rotor`**) | Integer multiply |
| `^` | Outer product | **XOR** |
| `|` | Contraction / inner-style product | **OR** |
**Type-directed disambiguation** chooses algebra vs bitwise. **Do not** mix metaphors inside one expression without matching types.
**Pattern from `examples/hello_4d.r4d`:**
```roma4d
a: vec4 = pos[0] * rot
b: multivector = pos[0] ^ demo_mv
c: float = pos[0] | demo_mv
i: int = 3 ^ 5
j: int = 1 | 2
```
---
#### 10. Classes, `soa`, and `aos`
```roma4d
class Particle:
soa pos: vec4
soa vel: vec4
```
- **`soa`** declares **column / linear** fields with Ownership 2.0 semantics (§11).
- **`aos`** exists as a layout keyword; **prefer `soa`** unless you have a verified pattern.
**Construction:** **`Particle()`** lowers to a runtime symbol (see `roma4d_rt.c`).
---
#### 11. Ownership 2.0 (linear SoA, borrows, taint)
**All enforcement is compile-time.** The native binary does not execute a Rust-style borrow checker at runtime.
##### 11.1 Linear `soa` field access (canonical pattern)
```roma4d
cell: Particle = Particle()
col: vec4 = cell.pos # move out
col = col * rot
cell.pos = vec4(x=0, y=0, z=0, w=1) # write back before next read
again: vec4 = cell.pos
```
**Failure modes**
| Diagnostic | Meaning | Fix |
|------------|---------|-----|
| `UseAfterMoveError` | Read **`soa`** field again without re-assigning. | Assign **`cell.pos = ...`** before second read. |
| `BorrowError` | Overlapping **`borrow` / `mutborrow`**. | Narrow borrow scope; never borrow the same name conflictingly. |
| `TaintError` | Value flowed through **`print(...)`** then assigned into **linear / `soa`** slot. | Do not connect `print` outputs to **`soa`** writes. |
##### 11.2 `borrow`, `mutborrow`, `timetravel_borrow`
- Operand must be a **simple identifier** matching the borrow pass expectations.
- **`timetravel_borrow(rotor)`** appears inside **`spacetime:`** in **`hello_4d.r4d`** as a chronology narrative hook.
---
#### 12. Spacetime: `t`, `@ t`, `spacetime:`
**Compile-time staging:** these constructs participate in **static** MIR / type reasoning. They **do not** magically run a 4096-tick interpreter for you unless you wrote explicit loops yourself in normal statement code.
**`t` coordinate**
```roma4d
_tau: time = t
sample: vec4 = worldtube[0] @ t
```
**`spacetime:` regions**
```roma4d
spacetime:
par for p in worldtube:
p = p * rot
_hold = timetravel_borrow(rot)
```
**Multiple `spacetime:` blocks** at the **same** indentation level are used in **`demos/spacetime_collider.r4d`** (“frames”). That is **sequential** regions, not nesting.
**LLM rules**
- **Do not** place **`spacetime:`** **inside** a runtime **`for`** loop unless you **know** it is valid for your target—**not** demonstrated in canonical demos.
- **Do not** expect **`spacetime:`** alone to iterate **tick** counters—use normal **`for tick in range(n):`** **outside** if you need counted steps, and use **`print("literal")`** for each milestone if you cannot format integers.
---
#### 13. Parallelism: `par for`
```roma4d
spacetime:
par for p in positions:
p = p * rot
```
**Semantics (today)**
- Structured parallel loop with **sendability** / capture checking in the ownership pass.
- SIMD-friendly lowering exists for some **`vec4` * `rotor`** patterns.
- Full CUDA GPU execution is **not** the default end-to-end experience.
**Critical pattern:** iterate **directly** over **`list[vec4]`** binding **`p`** as the element, then assign **`p = p * rot`**. **Do not** rewrite as **`par for i in range(N): cosmos[i] = ...`** unless you **know** it is supported—the happy path is the **`par for p in cosmos`** form (see §22).
---
#### 14. Lists and comprehensions
**Construction**
```roma4d
xs: list[vec4] = [vec4(x=0, y=0, z=0, w=1) for _ in range(N)]
```
**Indexing**
- **`xs[i]`** reads an element.
- Updates inside **`par for p in xs`** should use the **`p = ...`** pattern, not index loops, unless you **verify**.
**LLM rule:** **`list[vec4]`** scales with memory—**1_000_000** is the canonical demo scale; **10_000_000** appears in **`demos/cosmic_genesis.r4d`** and is heavier.
---
#### 15. Systems: `unsafe:` and MIR hooks
```roma4d
unsafe:
rawp: rawptr = mir_alloc(128)
mir_ptr_store(rawp, 42)
_peek: int = mir_ptr_load(rawp)
```
Requires **`[systems] unsafe = true`**. **`gc = false`**—no tracing GC.
---
#### 16. Native runtime (`rt/roma4d_rt.c`)
Linked from **`pkgRoot/rt/roma4d_rt.c`**. Provides C symbols used by LLVM lowering, including **`print` → `puts`**, **`vec4`**, **`rotor`**, **`multivector`**, **`Particle`**, and demo hooks calling **`curl`** for Ollama.
**Numeric printing:** not a general **`printf` bridge** from Roma4D for arbitrary **`float`** formatting—use **fixed strings** or extend C if you need digits.
---
#### 17. Ollama / HTTP demos (builtins)
##### `ollama_demo()`
- Requires **`curl`** on `PATH` and local **Ollama** (`ollama serve`, default `http://127.0.0.1:11434`).
- JSON body is **fixed in C** (dynamic string building from `.r4d` is not the general story).
##### `quantum_server_demo()`
- Same infrastructure.
- Env: **`QUANTUM_QUERY`**, **`QUANTUM_CONTINUE=1`** (see `demos/quantum_server.r4d`).
**Security:** uses **`system("curl ...")`** from C—trusted local dev only.
---
#### 18. Compilation pipeline
1. Parse primary + imported modules.
2. Typecheck + resolve imports + attach builtins.
3. Ownership 2.0 pass.
4. Lower AST → MIR.
5. MIR → LLVM IR.
6. **`zig cc` or `clang`** compile `.ll` → `.o`, link **`roma4d_rt.c`** → executable.
---
#### 19. Debugging, logs, and common failures
##### `debug/last_build_failure.log`
On failure, a structured record is appended under **package root** **`debug/last_build_failure.log`**: stage, argv, stderr, LLVM IR head. In **forgiving** mode, the **Native AI Expert** also appends a block under stage **`ai_expert`** (see **§29**).
##### `R4D_DEBUG=1`
Mirrors failure details to stderr immediately (Unix / Windows / PowerShell).
##### Zig vs Clang (Windows)
- **Install Zig** and put it on **`PATH`**—simplest path.
- **Clang fallback:** if you see **`mm_malloc.h`** errors, set **`R4D_GNU_ROOT`** to your MinGW prefix (e.g. `C:\msys64\ucrt64`) or **install Zig**.
##### Linux `sqrt` undefined
Preserve **`-lm`** when customizing links; the driver adds it on non-Windows.
##### Indentation errors
Mixed tabs/spaces cause **`INDENT` / `DEDENT`** parse failures—reformat uniformly.
---
#### 20. Example programs (indexed)
| Path | What it proves |
|------|----------------|
| `examples/min_main.r4d` | Smallest **`main() -> int`**, exit **42**. |
| `examples/hello_4d.r4d` | **Imports**, **GA ops**, **SoA**, **`t` / `@ t`**, **`spacetime` + `par`**, **`unsafe` + `mir_*`**, **`timetravel_borrow`**. |
| `demos/spacetime_collider.r4d` | Large **`list[vec4]`**, multiple **`spacetime:`** frames, **`Particle`** witness, narrative **`print`**. |
| `demos/causal_oracle.r4d` | **`ollama_demo()`** integration. |
| `demos/quantum_server.r4d` | **`quantum_server_demo()`** + env vars. |
| `demos/cosmic_genesis.r4d` | **10M** `list[vec4]`, **`par for`** rotor sweep, epic static transcript. |
| `libgeo.r4d` | Importable **`bump`**, **`identity_v4`**. |
**When asked for “the most advanced single file”:** start from **`spacetime_collider.r4d`** and **remove** features you cannot justify—not the other way around.
---
#### 21. File extensions
| Ext | Status |
|-----|--------|
| **`.r4d`** | **Official** |
| **`.r4s`** | Legacy |
| **`.roma4d`** | Legacy |
---
#### 22. Python vs Roma4D — invalid pattern encyclopedia
Each row is a **hard “do not generate”** unless the Roma4D compiler explicitly gains support and this guide is updated.
| Wrong pattern | Why | Use instead |
|---------------|-----|-------------|
| **`f"…{x}…"`** | No f-strings | **`print("literal")`**, separate prints |
| **`print(n)`** for **`int`/`float`** | Weak / non-portable runtime formatting | Fixed strings only |
| **`time()` / `sleep()`** | No such builtins | **`t`** token; external benchmarking via **`-bench`** |
| **`[T; N]`**, **`Vec4`**, **`float4`** | Wrong language | **`list[vec4]`**, **`vec4(...)`** |
| **`cosmos: [Particle; N] = …`** | Invalid | **`list[vec4]`** + **`Particle()`** witness if needed |
| **`import *`** | Hard error | **`from m import a, b`** |
| **`import os`, `import sys`, PyPI** | No linkage model | **`from libgeo import …`** or new **`.r4d`** module |
| **Nested `spacetime:` inside `for`** | Not in canonical demos | Sequential **`spacetime:`** blocks or outer structure |
| **`par for i in range(N): a[i] = …`** | Not the proven SIMD path | **`par for p in a: p = p * rot`** |
| **`async` / `await` / `lambda`** | Unsupported lowering story | **`def`** + straight-line code |
| **`try`/`except` as control flow** | Unstable for generators | Write type-safe code |
| **`open("f.txt")`**, **`requests`** | No builtins | C / future FFI (not here) |
| **`numpy` / `torch`** | Wrong runtime | **`list[vec4]`** + **`par`** |
| **`if __name__ == "__main__"`** | Meaningless | **`def main()`** only |
| **`# type: ignore`** | Meaningless | Fix the type |
| **Dynamic SQL / HTTP in `.r4d`** | No string runtime | **`ollama_demo`** / C |
---
#### 23. Compiler and linker error catalog
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `source file not found` | Bad relative path / cwd | **Absolute path** to `.r4d` |
| `not a Roma4D source file` | Wrong extension | **`.r4d`** |
| `could not find Roma4D installation` / `roma4d.toml` | Outside tree + no env/embed | Run **`.\scripts\Install-R4dUserEnvironment.ps1`** once, new terminal, then **`r4d yourfile.r4d`** |
| `ImportError` | Missing module file | Add **`libfoo.r4d`** at correct path |
| `import * is not supported` | Python habit | Named imports |
| `UseAfterMoveError` | SoA linearity | Write-back **`cell.pos`** |
| `BorrowError` | Overlapping borrows | Narrow scope |
| `TaintError` | `print` → `soa` | Break the dataflow |
| `mm_malloc.h` / MinGW | Clang without Zig | **Install Zig** or **`R4D_GNU_ROOT`** |
| `zig cc` failed | Zig missing | **`PATH`** / **`R4D_ZIG`** |
| `synthesized return` | `-> int` without `return` | Add **`return 0`** |
---
#### 24. Ergonomics: `r4`, `GOBIN`, `R4D_PKG_ROOT`, embedded root
- **`go install ./cmd/r4 ./cmd/r4d ./cmd/roma4d`** puts binaries in **`go env GOBIN`** if set (e.g. conda **`…\Scripts`**), else **`GOPATH\bin`**.
- **`scripts/Install-R4dUserEnvironment.ps1`** (recommended on Windows): appends that **install directory** to **user** **`PATH`**, sets **`R4D_PKG_ROOT`**, optionally **`R4D_GNU_ROOT`** for Clang+MinGW, and runs **`go install`** with **`-ldflags -X …cli.EmbeddedPkgRoot=…`** so **`r4d C:\anywhere\sketch.r4d`** works after a new terminal.
- **`install.ps1`** / **`install.sh`**: same **embedded root** pattern for developers who **`go install`** from the repo.
- **`r4d.ps1`** / **`r4d.cmd`**: developer launcher at repo root—**`Set-Location $PSScriptRoot`**, **`go build`** into Go bin, prepend **`PATH`**, then **`& r4d.exe @args`**. No args → prints a short usage box and **`r4d help`**.
- Plain **`go install`** without **`-ldflags`**: **no embedded root**—either keep sources under a tree that contains **`roma4d.toml`** or set **`R4D_PKG_ROOT`** / **`ROMA4D_HOME`**.
- **CLI errors:** “file not found” suggests a **full path** example; “could not find Roma4D installation” points at **Install-R4dUserEnvironment.ps1** and **`r4d yourfile.r4d`**.
---
#### 25. LLM code-generation protocol (step-by-step)
**Phase A — Requirements extraction**
1. Does the user need **exit code**? → **`main() -> int`** + **`return`**.
2. Otherwise → **`main() -> None`**.
3. Do they need **imported helpers**? → only **`from import …`** (`libgeo`).
**Phase B — Data model**
1. Bulk field in 4D? → **`list[vec4]`**.
2. Need SoA story? → **`class`** with **`soa pos: vec4`** + **`Particle()`** witness (see collider demo).
3. Pick **`N`**: **`1024`**, **`1_000_000`**, or (heavy) **`10_000_000`**.
**Phase C — Math**
1. Rotations → **`rotor(angle=…, plane="xy"|"yz"|"xw")`**.
2. Apply with **`*`** on **`vec4`**.
**Phase D — Parallelism**
1. Wrap **`par for`** in **`spacetime:`** like **`hello_4d.r4d`**.
**Phase E — Narrative I/O**
1. **`print("fixed line")`** only.
**Phase F — Self-verify**
1. Run **[§26 checklist](#26-pre-submit-checklist-copy-for-every-generation)**.
---
#### 26. Pre-submit checklist (copy for every generation)
- [ ] Filename ends with **`.r4d`** (or legacy only if requested).
- [ ] **`def main()`** exists; no `__main__` guard.
- [ ] **Return discipline:** `-> int` always returns **`int`**; `-> None` uses **`return None`** or omits.
- [ ] **No f-strings**; **no `time()`**; **no `import *`**; **no PyPI**.
- [ ] **4D math** uses **`vec4` / `rotor` / `multivector`**, not Rust/C++ types.
- [ ] **SoA:** every **`cell.pos` read** paired with **write-back** before second read.
- [ ] **`par for`** over **`list`**, not index loop, unless verified.
- [ ] **`spacetime:`** structure matches **`hello_4d`** / **`spacetime_collider`** (no nested-in-`for` unless verified).
- [ ] **`print`** uses **string literals** only.
- [ ] **Imports** name real symbols from **`libgeo.r4d`** (or other existing files).
- [ ] Tell human to run **`r4d file.r4d`** and read **`debug/last_build_failure.log`** on failure.
---
#### 27. LLM hard rules (non-negotiable)
1. Output **only** **`.r4d`** (unless user explicitly requests legacy extensions).
2. **Never** claim CPython semantics for **`print`**, **`str.format`**, **`time()`**, or **f-strings**.
3. **Never** invent **stdlib** modules beyond local **`.r4d`** files in the package root.
4. **Always** use **`vec4` / `rotor` / `multivector`** for geometric code—never **`Vec4` / `float4`**.
5. **`main() -> int`** must end with an **integer `return`** on all paths.
6. If unsure about a feature, **omit** it—**`print("ok")`** beats a hallucination.
7. After code, instruct: **`r4d .r4d`**, **`--strict`** for CI, **`R4D_DEBUG=1`**, and **`last_build_failure.log`**.
---
#### Appendix A — Drop-in safe template (verified shape)
Copy this when the user gives no extra constraints. It matches **`examples/hello_4d.r4d`** minus optional extras:
```roma4d
### sketch.r4d — minimal safe Roma4D scaffold (adjust N for memory)
from libgeo import bump, identity_v4
class Particle:
soa pos: vec4
soa vel: vec4
def main() -> None:
_seed: int = bump(0)
rot: rotor = rotor(angle=1.5707963267948966, plane="xy")
worldtube: list[vec4] = [vec4(x=0, y=0, z=0, w=1) for _ in range(1024)]
_tau: time = t
w: vec4 = worldtube[0] @ t
_ = identity_v4(w)
cell: Particle = Particle()
col: vec4 = cell.pos
col = col * rot
cell.pos = vec4(x=0, y=0, z=0, w=1)
spacetime:
par for p in worldtube:
p = p * rot
print("ok")
return None
```
---
#### 28. Document maintenance
When the compiler changes, update:
| Area | File(s) |
|------|---------|
| Builtins | `src/compiler/typechecker.go` (`seedBuiltins`) |
| Extensions / resolution | `src/compiler/source_ext.go` |
| Native AI Expert | `src/ai/expert.go` (terminal debug, interactive, LLM briefing) |
| Keywords | `src/parser/token.go` |
| CLI / pkg root | `internal/cli/cli.go` |
| Windows install + PATH | `scripts/Install-R4dUserEnvironment.ps1`, `r4d.ps1`, `r4d.cmd` |
| Linker | `src/compiler/llvm_link.go` |
| Void main ABI | `src/compiler/codegen_llvm.go` |
| Runtime | `rt/roma4d_rt.c` |
| **This guide** | `docs/Roma4D_Guide.md` |
---
#### 29. Native AI Expert (terminal debug + interactive)
**What it is:** A **built-in**, **zero-network** assistant that runs when **`r4d` / `roma4d` / `r4`** fails to compile or link a **`.r4d`** file in **forgiving mode** (the default). It does **not** call external LLMs; it uses curated rules aligned with this guide.
##### 29.1 Terminal debug block (always in forgiving mode)
On failure, stderr receives a bordered block you can **copy in full** for humans or for an external LLM. It includes:
| Section | Contents |
|--------|-----------|
| Header / footer | `ROMA4D EXPERT DEBUG` lines (easy grep / paste boundaries) |
| Metadata | UTC time, `GOOS`/`GOARCH`, Go version, tool name, action, source path, package root (if known), inferred line |
| Raw message | Verbatim compiler / linker / driver text |
| Source context | A few lines around the inferred error line (`bufio.Scanner` on the source file) |
| Symptom hints | Short bullets mapping this failure to guide sections (e.g. SoA §11, Zig §19) |
| Copy/paste commands | Examples: `r4d C:\full\path\file.r4d`, `R4D_DEBUG=1`, `winget install Zig.Zig`, `pip install PyQt5` when relevant |
| Guide memory | Pointers to the normative sections of **this document** |
| **LLM_INSTRUCTIONS** | A ready-to-paste briefing telling an assistant to output only valid **`.r4d`** per §27 / §22 |
**Strict mode:** `r4d --strict ...` skips the entire Expert path and prints a minimal one-line error.
##### 29.2 Log file
The same session is **appended** to **`debug/last_build_failure.log`** under the **package root** (via `compiler.WriteBuildFailureLog`, stage `ai_expert`). Structured linker failures from the driver may also append earlier rows for the same run.
##### 29.3 Interactive Expert (TTY only)
If **stdin is a terminal** (detected with `golang.org/x/term`), after the debug block the Expert may:
1. Show a **suggested edit** for high-confidence cases (e.g. `import *` → explicit imports) and prompt **Done? [y/N]** (acknowledgment — you apply the edit in your editor).
2. Open a small **REPL**: type **`why`**, **`zig`**, **`pyqt`**, **`guide`**, **`llm`**, **`strict`**, **`help`**, or **`quit`**.
**Disable interactive mode** (keep the printed debug block): set **`R4D_EXPERT_INTERACTIVE=0`**.
##### 29.4 Implementation rules (for contributors)
- **Regex:** All patterns in `expert.go` use **`regexp.MustCompile`** at package scope.
- **File reads:** Source context uses **`bufio.Scanner`** with an explicit buffer cap (no unbounded slurp of huge files).
- **Panic safety:** The Expert **`defer recover()`** fail-opens to a short raw error line if something unexpected panics.
- **Python vs Roma4D:** The Expert reminds users that **`.py`** is delegated to CPython via **`r4d script.py`**; **`.r4d`** stays on the native pipeline (see CLI help).
##### 29.5 Quick reference for users
| Goal | Command / action |
|------|-------------------|
| Rich failure help | Run without `--strict` (default). |
| CI / scripts only | `r4d --strict file.r4d` |
| Skip post-mortem prompts | `R4D_EXPERT_INTERACTIVE=0` |
| Mirror linker details | `R4D_DEBUG=1` (see §19) |
| Feed an external LLM | Copy from **`LLM_INSTRUCTIONS`** through **`END_LLM_INSTRUCTIONS`** in the debug block |
---
*End of Roma4D Elite Reference Guide.*