commit.txt

ALFS persistence, Hebrew glyph rendering, built-in programs, Frobenius orbit REPL command

## What Changed

### Fixed: ALFS Mount (src/alfs.rs)
- `mount()` now sets `ATA_DRIVE = 1` BEFORE reading the superblock
  Previously the superblock was read from drive 0 (boot disk), magic check always failed,
  ALFS never mounted, and `:files` always returned "[ERROR] Filesystem not mounted"
- Removed the redundant `ATA_DRIVE = 1` assignment that was (unreachably) after the magic check

### Fixed: :save wired to ALFS (src/aleph_repl.rs)
- `:save` previously wrote to the in-memory SefirotFs (lost on reboot, invisible to :files)
- Now calls `alfs::write_file(filename, data, TYPE_ALEPH)` directly
- Files saved via `:save` now appear in `:files` and persist across reboots in alfs.img

### New: Hebrew Bitmap Glyph Rendering (src/aleph.rs, src/font_renderer.rs)
- `display_glyph()` is now display-mode-aware:
  - Framebuffer mode: returns raw byte `0xE0 + letter_index` — `render_char()` maps this
    to the hand-drawn `HEBREW_FONT` bitmaps in `vga_font_data.rs`
  - VGA text mode: returns ASCII transliteration (A, B, G, D...) as before
- Added `HEBREW_GLYPH_BYTES: [[u8; 1]; 22]` static — one raw code-point byte per letter
- `from_utf8_unchecked` used safely: the write path treats each byte as a raw code point,
  not as UTF-8 text; framebuffer `render_char` handles the 0xE0–0xF5 range explicitly
- Hand-drawn glyphs (א ב ג ד ה ו ז ח ט י כ ל מ נ ס ע פ צ ק ר ש ת) now render natively
  in graphical mode

### Fixed: Font Scale (src/font_renderer.rs)
- `SCALE` reduced from 2 to 1 (native 8×16 pixels per character)
  At SCALE=2 each character was 16×32px, causing severe screen overflow on every command

### New: nearest_letter() (src/aleph.rs)
- `pub fn nearest_letter(t: &Tuple) -> &'static LetterDef`
  Finds the canonical letter with minimum weighted distance to a given tuple
  Used by `:orbit` to name the current state at each iteration step

### New: Built-in Program Registry (src/programs.rs, src/lib.rs, build.rs)
- `src/programs.rs`: all 13 `.aleph` files in `programs/` embedded via `include_bytes!`
- `seed_alfs()`: writes each built-in program to ALFS on boot if not already present
  — fresh `alfs.img` is fully populated automatically, no host-side tool needed
- Called from `main.rs` immediately after `alfs::mount()` succeeds
- `build.rs` now watches `programs/` — any file change triggers a recompile
- Programs registered: creation, creation_liturgy, distance_probes_indistinguishable,
  exploration_primitives, frobenius, frobenius_orbits, light_replication_kernel,
  light_stability, meditation, pratyahara, selfreplicating_light,
  tikkun_construction_full, tikkun_construction_partial, tikkun_palace_verification

### New: :orbit Command (src/aleph_repl.rs)
- `:orbit N letter pole` — live iterative Frobenius convergence in the REPL
- Applies `state = state ⊗ pole` N times from `letter`
- Each step prints: step number, nearest canonical letter (by weighted distance),
  ouroboricity tier, distance to pole, convergence delta
- Color-coded output: green = converging, cyan = fixed point, red = diverging
- Exits early when distance < 0.01 (fully converged)
- Usage: `:orbit 8 aleph vav`, `:orbit 6 dalet shin`, `:orbit 10 tav mem`
- Added to `:help` text

### New: frobenius_orbits.aleph (programs/frobenius_orbits.aleph)
- Unrolled 4-step convergence study for all three O_inf poles
- Demonstrates: self-idempotency (`vav x vav → d=0`), cross-pole closure (tier check),
  convergence orbits for aleph→vav / tav→mem / dalet→shin, mediation stability through
  poles as witnesses, and second mediation layer
- Ends with inter-orbit distances and :census

### Updated: Documentation (README.md, USAGE.md)
- README.md: run commands updated to `./run.sh` / `./run.sh --serial` (UEFI OVMF);
  ALEPH syntax table uses parser-accepted forms (x, v, ^, not ⊗, ∨, ∧);
  :orbit documented with example; :files/:save/:load/:run documented;
  programs table with all 14 files; project structure updated with new source files;
  BT-2 corrected ("converges in ≤ 2 steps for any letter")
- USAGE.md: fully rewritten — old version referenced broken legacy bootloader and
  wrong binary names; now covers UEFI boot, run.sh modes, ALFS layout, seeding,
  all REPL commands, :orbit, per-program descriptions, Hebrew glyph pipeline,
  ATA API, ALFS API, nearest_letter, and updated troubleshooting section

## Boot Output (current)
[BOOT] Heap: initialized (4MB)
[BOOT] UEFI GOP Framebuffer: NxN @ 32bpp
[exoterikOS] Phi_c Kernel fully online. Type 'help' for commands.
[FS] ALFS v1: 14 files, 0 used / 1024 free sectors - files: 14
exOS>

## ALEPH REPL — new capabilities
A> :orbit 8 aleph vav        # live convergence orbit, color-coded per step
A> :files                    # lists all 14 programs from ALFS
A> :save mywork              # saves last result to ALFS (persists across reboots)
A> :run frobenius_orbits     # 4-step unrolled convergence demonstration

## Design Principle
The persistent layer (ALFS) and the display layer (Hebrew bitmaps) are now fully
operational. Programs written in the ALEPH language and stored in programs/ are
compiled into the kernel binary, seeded to disk on first boot, and runnable or
loadable from the REPL without any host-side tooling.