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.*