LithosAnanake/.claude/CONSOLE.md

CONSOLE.md — Console VM Architecture (DRAFT)

StarshipOS / StarForth — Captain Bob (Robert Allan James)

This document constrains Claude Code behavior once Console work begins. Read it

completely before touching any Console code.

STATUS: design-stage draft, 2026-08-02. Nothing described here is implemented yet.

This is the output of a planning conversation, captured so it can keep being

refined instead of living only in chat history. Do not treat anything below as

"already built" — there is no Console code in the tree yet.

---

SUPERSEDED (Captain Bob, 2026-08-15). This document is no longer authoritative, and its core premise below ("Console is a 4th Tripod VM, Quadrupod, StarForth-dialect-only") was architecturally reversed by a later, decided ruling: FABRIC.md §17.5 — the framebuffer is a utility, not a patron, not a VM. What actually shipped is direct C (src/starkernel/hal/console.c/vt100.c/framebuffer.c plus keyboard drivers), called straight from the kernel, no Hera-spawned Console VM anywhere. FABRIC.md/FABRIC-2.md (repo root — read FABRIC-2.md first) are the sole design-of-record for Console/framebuffer work now. Kept here as historical record only. See .claude/CLAUDE.md's own pointer.

---

The Pivot This Document Reflects

Console was first framed as "wrap the existing bitmap/VT100 framebuffer driver in a 4th Tripod VM." That framing is superseded. The framebuffer is now treated as a drawing fabric: full-color, Cartesian-addressed, rasterized-vector — not a character-cell bitmap terminal. Text is one thing drawn on the fabric, not a special case. Rationale (Captain Bob, verbatim intent): everything in the eventual GUI is going to be drawn anyway, so the console should be drawn the same way from the start rather than built on a bitmap terminal that gets thrown away later.

The existing src/starkernel/hal/framebuffer.c (raw UEFI GOP pixel plotting) is still the right low-level substrate — that part is reused. font_8x16.c and vt100.c (the bitmap-cell VT100 emulator built on top of it) are what's being superseded; see Open Decisions below for their fate.

---

Language Constraint — Non-Negotiable

All Console implementation is in StarForth dialect ONLY, with the same narrow exception every other Tripod VM has: raw hardware access (the actual pixel write into GOP framebuffer memory) is C, registered directly as Forth primitives — exactly how BLOCK/UPDATE/FLUSH/RANDOM/SEED already work. Everything above that raw pixel-write boundary — glyph composition, cursor logic, dirty-cell tracking, VT100 semantics, fonts — is StarForth.

C99 beyond that narrow hardware boundary is forbidden unless explicitly blocked in StarForth AND explicit written permission is given by Captain Bob for that specific construct. "I could not figure out how to do this in StarForth" is not permission. Ask first. Wait for the answer.

---

When Stuck — Non-Negotiable

If you are stuck, STOP.

Do not confabulate. Do not invent dictionary words that do not exist. Do not fabricate primitives. Do not guess at behavior. Do not work around the problem silently.

STOP. Report exactly what is blocking you. Wait for instruction.

---

What Console Is

Console is the fleet's fourth leg — Quadrupod, not Tripod. A real StarForth VM, spawned by Hera, participating in fleet K≡1.0 like Hermes and Artemis. Its contract: Console owns the drawing fabric (the framebuffer) and, in a later phase, keyboard input. It renders. It does not route messages (Hermes), does not own persistent storage (Artemis), and does not make VM lifecycle decisions (Hera).

Mythological name: not yet chosen. Candidates raised (Argus, Iris, Hestia) were not settled on. Do not pick one unilaterally when implementation starts — ask Captain Bob. This document uses "Console" as a working label until named.

---

Coordinate System

True Cartesian: origin bottom-left, Y increases upward. This is a firm decision, not a placeholder. The framebuffer's native memory layout is top-left origin, Y-down (standard raster convention) — every drawing primitive that touches the framebuffer must apply the Y-flip transform. Get this at the lowest primitive layer so nothing above it ever has to think about it again.

---

Primitive Layer — C, registered directly as Forth words

Raw, hardware-touching, absolute-coordinate. Not turtle/relative — see Font & Pen Layer below for why the split falls here.

• PLOT ( x y color -- ) — set one pixel (post Y-flip transform)
• LINE ( x1 y1 x2 y2 color -- ) — Bresenham line between two absolute points

Absolute coordinates were chosen deliberately: the long-term direction (wireframes — triangles/quadrangles, eventually textured/shaded) is fed by projected vertex data, which is naturally absolute per-vertex, not relative turtle deltas. Building the hardware boundary around absolute coordinates means the eventual triangle-fill / texture-sample primitives extend this layer instead of fighting it.

Performance principle — non-negotiable: the actual per-pixel work (Bresenham walk, eventually triangle rasterization, texture sampling) must live in this C layer, compiled. Forth orchestrates — decides what to draw and when — but never walks pixels one at a time through the interpreter. This is the same C-does- hardware / Forth-does-policy split every other Tripod VM already uses; it is not a new rule invented for Console, just applied here.

Known unknown: actual achievable frame rate. Feasible in principle (this is how every pre-GPU software-rasterized engine worked), but unmeasured, and QEMU TCG (the only acceptance environment per .claude/CLAUDE.md) will be meaningfully slower than real hardware for CPU-emulated per-pixel work. Do not assume a frame-rate target without measuring on the actual target environment first.

---

Font & Pen Layer — StarForth, composable

Fonts are not a C data table. Each glyph is a StarForth word, e.g. GLYPH-A ( x y -- ), expressed as a short sequence of pen strokes relative to the glyph's origin — a small pen DSL (STROKE dx dy, pen up/down, within a unit em-box) that resolves down to calls into the absolute LINE primitive. This is deliberately hackable: a font is just another .4th capsule, content-addressed and hash-verified exactly like every other capsule in this system. Swap the capsule, get a different typeface. No new loading mechanism — the existing capsule system already does this.

This does not fight the performance principle above: glyph composition is a handful of word dispatches (5–15 strokes per character), not per-pixel work. The expensive part — actually writing pixels — stays in the C LINE primitive regardless of how the glyph was authored. Combined with heat-driven redraw (below), most glyphs aren't recomposed most ticks anyway.

A thin turtle/pen convenience layer (position + heading state, FORWARD/RIGHT/ PENUP/PENDOWN) may be built on top of the same absolute LINE primitive for generative drawing use cases. It is StarForth-only, costs nothing at the C layer, and does not change the hardware-boundary decision to stay absolute.

Phase 1 requires the full printable-ASCII stroke-glyph table, not a subset — a VT100-equivalent terminal needs to render arbitrary text from day one. A narrower subset only made sense as a pipeline smoke test in isolation, which is no longer the goal.

---

Heat-Driven Redraw Model

Screen redraw is dirty-cell tracking, expressed in the same compudynamic vocabulary as everything else in this system — not decorative, it's the actual mechanism.

• Each screen cell carries a heat value, structurally the same idea as BLK-HEAT for Artemis's data blocks.
• A cell goes hot (Q.1) the moment its content changes.
• Console's own tick (driven off Hera's fleet heartbeat, same pattern as ART-TICK) scans for hot cells only.
• For each hot cell, Console redraws it via the glyph/LINE primitives — and that redraw is the reap event. Heat goes to zero because the work got done, not because of a time-based decay curve like Artemis blocks or Hermes messages.
• Cells at K=0 are skipped entirely this tick — untouched pixels, no wasted work.

This cell-heat contributes to Console's share of fleet K, same as every other compudynamic object in the system. Reap (redraw-to-zero) must rebalance K correctly, same invariant every other VM already honors.

---

Immediate Goal

Scope for the first real implementation pass. Nothing past this section is authorized to build yet.

The target: a VT100-equivalent interactive terminal, rendered entirely through the vector fabric described above (not the old bitmap driver), with:

1. Console spawns as the fleet's 4th leg under Hera's birth protocol, joins fleet K≡1.0 like Hermes and Artemis.
2. Full printable-ASCII stroke font, composable/StarForth-authored, loaded as a capsule.
3. Cursor positioning, basic scrolling, and enough VT100 semantics to be a usable terminal — the same functional bar the current bitmap vt100.c already clears, just achieved through the new fabric instead.
4. Heat-driven redraw — only changed cells get rasterized per tick.
5. Text arrives at Console the same way everything else moves between Tripod VMs: via Hermes. Console does not invent a second message-passing mechanism.

Explicitly out of scope for this phase: keyboard input (see Future Material — there is no keyboard driver anywhere in this codebase yet, this is a separate, substantial piece of work), double buffering (open decision, see below), the wireframe/textured/shaded GUI vision (that's the reason the fabric is built this way, but building it is a different, later phase).

---

Open Decisions — must be settled before or during implementation

1. Mythological name. Not chosen. Ask Captain Bob before implementation starts.
2. Fate of font_8x16.c / vt100.c. Kept only for pre-Console boot diagnostics (before Console VM is alive to take over), or retired outright once the fabric is proven? Not decided.
3. Double buffering. Direct framebuffer writes will tear once Console is doing partial redraws every tick instead of static boot text. Cheaper to decide now than to retrofit through every draw call later. Not decided.
4. Actual frame-rate/performance numbers. Unmeasured. Do not commit to a real-time target without benchmarking on real hardware and under QEMU TCG separately — they will differ meaningfully.

---

FUTURE MATERIAL — Not In Scope

Everything below is real direction, preserved intentionally, and is not part of the Immediate Goal above. Do not build any of this without Captain Bob explicitly reopening it — same rule ARTEMIS.md and TRIPOD.md already hold their own future chapters to.

Full wireframe GUI

Triangles/quadrangles from projected vertex data, applied textures and shading, anti-aliased/high-resolution appearance ("not blocky") even at small polygon sizes. Visually in the spirit of vector-display arcade games (Asteroids), rasterized in software onto the linear framebuffer — no GPU, no hardware acceleration available on this platform. The absolute-coordinate PLOT/LINE primitive layer is designed so triangle-fill/texture-sample primitives extend it later rather than replacing it.

Keyboard input

No driver exists anywhere in this codebase today. PS/2 8042 controller is the pragmatic first target — QEMU supports it cleanly. USB HID through the existing virtio/PCI stack is a materially bigger lift and should come later, if at all. M8: REPL keyboard input in the top-level roadmap has been "planned, not started" for the life of this project; this is the same gap.

Interactive REPL on the framebuffer

Once keyboard input exists, point a real interactive REPL loop at Console instead of (or alongside) the serial ok>. This is the piece that actually starts to make the system feel like an operating system rather than a kernel with a serial console. Depends entirely on keyboard input landing first.

Multi-window / multi-session

Not discussed in depth. Flagged here only so it isn't forgotten — if the fabric approach pans out, multiple independent drawing regions/sessions is a natural next question once single-console VT100-equivalent behavior is solid.

---

This document is a living draft, not yet authoritative in the sense TRIPOD.md/ ARTEMIS.md/HERMES.md are — those describe implemented, verified systems. This one describes a plan. Update it as decisions get made; do not let it drift out of sync with what actually gets built, the way the other three documents do not drift.