Review of the HolyC-native apps plan

Date 2026-10-27. Read-only review of docs/holyc-native-apps-plan.md (the plan), docs/core-apps-plan.md, docs/os-foundation-plan.md, the two research reports, desk3/01-core.HC to desk3/05-run.HC, spike/KsSpike.HC and scripts/. Nothing was built or run. Line numbers are of the files as of today.

Evidence labels: [V] verified by reading a local file or a primary source fetched today (URL given), [D] reported by documentation or a project README fetched today, [U] unverified (reasoning, memory or arithmetic; treat as a hypothesis). Every speed estimate is [U] unless it cites a measurement.

0. Verdict#

The plan is a good list of apps and an honest list of gaps, but it is sequenced as an application project when the real risks are in the platform underneath it. Four things are wrong or missing at the root:

1. It solves persistence and file exchange with a bridge that does not need to exist. TempleOS installs itself to a hard drive (scripts/boot-vm.sh:17 answers "n" to "Install onto hard drive?" [V]). Attach a disk and say yes: notes, settings, bookmarks and the whole dev loop survive reboots, with no channel, no daemon and no protocol. The channel is still wanted for fetch and host services, but it drops from "gate 1, everything depends on it" to "one service among several".
2. It builds the app framework and widget kit before fixing the renderer's cost structure, and the renderer is where every later gate ("render legibly at 2x", editors, a browser page) will hit the wall. The measured 23 to 25 ms per dragged window at 2880x1800 is not the emulator's floor; it is the sum of four fixable things inside 01-core.HC (a bytewise MemCpy, a per-pixel shadow, per-pixel function calls, x87 maths in pixel loops). The cheapest single win in the whole project is replacing TempleOS's MemCpy, which is REP_MOVSB [V], with an 8 or 16 byte per iteration copy: under TCG every rep movsb iteration is one byte.
3. It writes "native" apps against a shell that is a demo, not a framework: fixed NA=9 windows, one window per app, if (a==...) chains in three places, a 500-entry hit list that silently drops entries, no clip stack, no key-up or modifier handling, Esc reboots the desktop, and every dirty rectangle re-executes every app's draw code. The plan knows some of this ("App framework", "Widget kit v2") but underestimates it as M and does not list the event model, clipping, Unicode, threading or memory items at all.
4. It does not say what "a complete operating system that runs and looks like a modern OS" means for TempleOS V5.03, which cannot display this desktop on real hardware at all (the mode set uses QEMU's Bochs VBE ports 0x1CE/0x1CF, desk3/04-main.HC:9-13, spike/KsSpike.HC:9-13 [V]; V5.03 itself is 640x480 16-colour VGA). If the Temple family stays the base, the base should be ZealOS (variable-resolution 32-bit VBE, AHCI, a networking stack in development, UEFI via Limine, public domain [D]), not V5.03.

Recommendation on the base: keep the HolyC desktop as the showpiece and personality, do the renderer pass and the five native apps that TempleOS does well (editor, code editor with Run, terminal, notes, reader-mode browser over a host fetch service), and treat the "complete modern OS" goal as the Linux-plus-own-Wayland-shell track already written up in os-foundation-plan.md, with the HolyC desktop running inside it as one window. The conditions that would change that are in section 3.12.

1. Critique of the plan#

1.1 Wrong or shaky assumptions#

1.2 Missing work#

• Unicode and text. The kernel is 8-bit, the atlas is ASCII, TW and Txt skip anything outside 32 to 126. A browser, an email client and a messenger are mostly non-ASCII text in practice (names, quotes, dashes, accents, emoji). The plan's font row says "non-Latin" once and gives no path. See 3.3.
• Clipping and scrolling. The only clip is the dirty rectangle (ks_c0x..ks_c1y, 01-core.HC:36). Apps keep content inside windows by arithmetic (rows in Notes, FROWS in Files). A scroll view, a text field, a list and a browser viewport all need a push/pop clip stack intersected with the dirty rectangle. Not listed.
• Event model. Clicks are dispatched by numeric id ranges (04-main.HC:148-204,218-261), keys by FrontOpen index (:315-361), hover by a global ks_hot. There is no event struct, no capture/bubble, no focus object, no double-click, no right button (only ms.lb is read, :378), no key repeat policy. The plan's "app table with draw, click, key, close" is the right shape but is listed as M; with text fields, drag and drop, menus and modal sheets it is L.
• Threading. Everything runs in one task; Draw blocks input; the idle loop sleeps 5 ms (05-run.HC:123). A fetch, a page parse or a file copy will freeze the desktop. TempleOS Spawn takes a target_cpu (Kernel/KTask.HC [V]) and tasks share one address space, so a worker per core is cheap. Not mentioned anywhere in the plan.
• Memory. At 2x the desktop holds ten wallpapers of 20.7 MB plus bb and prev (about 250 MB of the 1 GB in boot-vm.sh:14) [V, arithmetic from 01-core.HC:35,655-656 and 04-main.HC:103-104], icon masks cached per size forever (ks_icm, 01-core.HC:514,571), and no budget for window layers, glyph caches, images or page DOMs. No -m increase, no eviction policy.
• Failure. TempleOS is ring 0 with one address space: a stray pointer in any app takes the desktop and the OS with it. HolyC has try/catch (used in 03-apps.HC:271-275), which is the only tool. The plan has no crash policy (auto-restart the desktop task? reboot to a snapshot?). For an OS that runs an AI agent and a browser against untrusted input this is the first security fact, and it is absent.
• Testing. scripts/snap.sh and the monitor socket exist [V]; there is no golden-screenshot test, no frame-time regression check, no per-commit boot. The browser gate ("20 pages lay out") needs exactly this harness.
• Real hardware. Nothing in the plan says where the OS eventually runs. V5.03 plus this desktop cannot display outside QEMU (A4, verdict point 4).

1.3 Sequencing#

The plan's order is channel, framework, services, browser B0, B1, editors, mail, network. Better:

1. Install to disk (hours). Removes the persistence gate.
2. Measurement harness and renderer performance pass (1 week, section 2). Every later item is cheaper to build against a renderer whose costs are known and whose primitives will not change under it.
3. Framework, event model, clip stack, input fix (modifiers, key-up, Esc no longer quits), widget kit v2 (3 weeks, not 2).
4. Text: host-built atlases for more ranges, sizes and weights; glyph cache by (face, size, codepoint); UTF-8 strings throughout (1 week). This is the first thing that makes the editor, the browser and mail possible.
5. Channel: raw-disk mailbox for bulk, serial for control (3 days), host service v0 (file exchange, fetch).
6. Browser B0 (reader mode) and the editor family.
7. B1 only after a B0 user test, with the page set chosen to fit.

1.4 Is desk3 a sound base? Code audit#

Keep: the logical/native unit split (01-core.HC:31-36,331-367), clipped spans and the corner coverage table (:130-176), the dirty-rectangle loop (02-ui.HC:24-71, 05-run.HC:28-54), immediate-mode widgets with hit registration (02-ui.HC:117-177), the Lucide stroke rasteriser with a per-size cache (01-core.HC:530-597), the per-phase timers for Monitor (05-run.HC:5-25). These are good ideas done simply.

Redesign now (cheaper now than after six apps are written against them):

The verdict on the base: the primitives are fine, the shell structure is a demo. Do the redesign in the framework step, before the editor, because the editor is the first app that needs clipping, focus, modifiers, UTF-8 and a line cache, and it will otherwise be written around the demo's limits and then rewritten.

2. Performance#

2.1 Where the time goes today (reasoning from the code and the measured numbers)#

• 64000 pixel loop in 1 ms (spike/KsSpike.HC:67-71, README) is 15.6 ns per back[j]=back[j]+0x010101. HolyC keeps j in memory and emits about ten instructions for that statement [U]; TCG on Apple Silicon runs a translated guest instruction in roughly 1 to 2 ns [U]. So the cost is HolyC's code generation times TCG, not TCG alone: a register-resident assembly loop should do the same in 3 to 5 ns per pixel, and a 16-byte SSE2 move in about 1 ns per pixel if the assembler had SSE (it does not [V]; 64-bit MOV pairs then, two pixels per instruction).
• A full 1280x800x4 copy in 7 ms is 0.59 GB/s, consistent with one translated loop iteration per byte (REP_MOVSB [V]).
• A dragged window at 2x (23 ms): per dirty rect (two per move, each about the window plus 88x90 logical of shadow margin, 02-ui.HC:68-71), Draw copies the wallpaper span by span (05-run.HC:7-8, MemCpy per row), then for every open window draws the shadow band (a 560x400 window at 2x with blur 68 native is about 280k Px calls [U, arithmetic]), the rounded fill, the ring, the app body, then the menubar backdrop and the dock. Estimate for one window: shadow 8 to 12 ms, body and fill 4 to 6 ms, copies 4 to 6 ms, the rest 2 ms. The shadow and the byte copies are the two biggest items.

2.2 Ranked wins#

Combined, wins 2 to 5 should bring a 2x window drag on this Mac from 23 ms to roughly 4 to 6 ms and a full-screen style crossfade from about 60 ms to about 15 ms [U]; win 1 makes the whole question go away and is the only one that gives headroom for a browser layout engine in HolyC. Win 6 is a multiplier on whatever remains.

2.3 Emulator configuration, briefly#

• -accel tcg,thread=multi is the default when supported; no flag needed. -accel tcg,tb-size= larger translation cache helps only if the working set thrashes (unlikely at this code size) [U].
• -cpu choice: keep a plain x86-64 model; AVX emulation exists but is slow and the assembler cannot emit it anyway.
• -display cocoa,zoom-to-fit=on scales 2880x1800 on the host each refresh; that is host time, not guest time. For measurement use -display none and screendump.
• QEMU 7.2 and later show TCG regressions for some x86 guests on Apple Silicon (a Windows 3.11 hang report, QEMU issue 2996 [D]); not our symptom, but pin the QEMU version used for measurements.

3. Better solutions by component#

3.1 Display and input path#

Plan: keep the Bochs VBE framebuffer, fix input "in the framework step". Right for QEMU. Add: the layer compositor (2.2 win 4), a clip stack, a proper cursor layer, modifiers and key-up from the scan code flags and kbd.down_bitmap [U], right and middle buttons, and a system chord instead of Esc. For real hardware the display path must be a boot-time VBE mode set in the boot loader, which is what ZealOS did [D]; V5.03 cannot do it.

3.2 Host channel#

Plan: serial streaming spike, else an IDE mailbox, else a NIC. Better order:

1. Installed disk for persistence (not a channel at all).
2. Raw second disk as a mailbox for bulk bytes both ways: guest BlkRead/BlkWrite through the existing ATA driver on a -drive if=ide,format=raw file the host also opens. A 4 KB header with sequence numbers, then a ring of blocks. Expected several MB/s with PIO under TCG [U]; no driver, no shared-memory ordering questions, works on any QEMU and on real hardware with a USB-free ATA disk. Cheapest experiment: write 1 MB from the host, read it in the guest, compare hashes, time it. One day.
3. Serial for control lines and events (it is duplex and already wired): stream with the FIFO, no acks, measure drops.
4. Shared RAM (memory-backend-file, share=on) only if latency below 1 ms matters (a live viewport). Unproven under TCG on macOS, as the earlier report says.
5. A virtio driver (serial or blk) later for interrupts and DMA; not first.

3.3 Fonts and text shaping#

Plan: port stb_truetype (about 5k lines) or keep host-built atlases. Better: host-built atlases now, a small rasteriser later, shaping never in the guest.

• Now: extend scripts/gen-font.py to emit a glyph index keyed by codepoint and more ranges (Latin-1, Latin Extended, Greek, Cyrillic, general punctuation, arrows, a monospace face, bold and italic), at the sizes a browser and editor use, plus a Noto Sans CJK subset if CJK is wanted (about 20k glyphs at two sizes is a few MB in 4-bit alpha). Add the kern pairs for the main face. This is days, not weeks, and covers email, chat and most of the document web.
• Later: a quadratic-outline scanline rasteriser in HolyC (TrueType glyf only, nonzero winding, 4x vertical oversampling, about 1500 lines) with an LRU glyph cache, for arbitrary sizes and web fonts. Under TCG a 24 px glyph rasterises in well under a millisecond [U]; cached, it does not matter.
• Shaping (ligatures, Arabic joining, Indic reordering), bidi and IME: do not write these in HolyC. If the OS ever needs them, the host service returns positioned glyph runs for a string (a "shape" request), which the guest paints with its cache. That keeps the guest honest about what it can do and matches the plan's own service model.

3.4 Web browser engine scope#

Plan: reader mode first, then HTML/CSS subset, then maybe JavaScript. Agree with reader mode first and with "document web" as the ceiling. Changes:

• Make B0 the product: reader mode plus a host-side HTML-to-display-list service for pages that reader mode mangles. A display list (text runs with font and colour, boxes, images, links with rectangles) painted natively is not screen capture; it is what the plan already names as the "clean fallback". With it, B1's layout engine becomes an optimisation, not a prerequisite for usefulness.
• B1 native layout: scope it as "block, inline, lists, tables, images, simple flex", with a conformance set chosen from pages that use only that. Drop "position basics" and "simple flexbox" from the first cut; add them after the page set passes.
• JavaScript: never in the guest (A8).
• Images: a host decode-and-resize service (the plan's option two) is right; PNG and JPEG decoders in HolyC are a later nicety.

3.5 Network and TLS#

Plan: host fetch service first, native stack optional. Right. For the native track, start from Shrine's stack (PCnet driver, TCP/IP, Wget [D]) or ZealOS's work, both public domain; write an E1000 or virtio-net driver against QEMU. TLS in HolyC (X25519, AES-GCM, SHA-256, certificate parsing, a root store) is months and will be slow under TCG; it is justified only on real hardware or KVM, and only if the OS is meant to be self-contained. Keep credentials on the host regardless.

3.6 Persistence and file systems#

Plan: host file service. Better: installed RedSea disk (3.2.1), plus a host RedSea tool to read and write the image when the VM is stopped and a mailbox file for live exchange. RedSea has no journaling, no permissions and no long-name hashing; fine for a single-user OS, not for a "complete OS" (section 4).

3.7 Audio#

Plan: host plays, guest controls (mpd/mpv). Right. A guest HDA or AC97 driver for QEMU (-device intel-hda plus hda-duplex, or AC97) is a few hundred lines of ring-buffer DMA and would let the music player be genuinely native for decoded PCM; decoding MP3 or AAC in HolyC under TCG is too slow to be worth it (an MP3 frame decoder is around 10 million operations per second of audio [U]). Order: host playback now, an AC97 driver as a weekend spike later, decoding on the host always.

3.8 Apps SDK#

Plan: app table and widget kit. Add: a written contract (draw context with clip and scroll, event struct, focus, invalidation API, timers, a worker-task helper), a component gallery that doubles as the golden test, UTF-8 everywhere, and a size limit per app file so the single concatenated build (scripts/send-to-vm.sh:14 [V]) stays fast to compile. HolyC's #include at run time already gives hot reload; use it: each app a file, reloadable without a desktop restart.

3.9 Packaging and updates#

Not in the plan. For the HolyC desktop: a manifest per app (name, icon, files, version), apps stored on the installed disk under one directory, an updater that pulls a package through the fetch service and verifies a hash. Shrine's Pkg is a public-domain reference [D]. Signatures need a hash and a signature verifier in HolyC (Ed25519 is about 1000 lines of C and runs fast enough once per package [U]).

3.10 AI agent integration#

Plan: host agent, approval for every write and command, native chat and diff panels. Right, and the only safe shape given ring 0. Add: the agent must never drive guest input directly without the "agent is driving" banner the earlier report proposed; all tool calls and their approvals logged on the host; the guest shows the exact command before approval. The engine's editor.* protocol and kosmos-mcp are the obvious transport once the channel exists.

3.11 Security and permissions#

In TempleOS there are none: no user separation, no memory protection, no sandbox, any app can read all memory and the whole disk. The plan's rule (nothing sent, deleted or purchased without a UI prompt) is therefore only as strong as the host daemon's enforcement of it. Write the permission broker on the host with per-app manifests, make the guest unable to reach the network or credentials by construction (it cannot), and treat anything the guest sends as untrusted input. Say this in the plan, because "security" for this OS is a host property.

3.12 The base OS question#

Recommendation: hybrid. Keep the HolyC desktop as the showpiece on the Temple family (move to ZealOS when the showpiece should leave QEMU), finish the renderer pass and the native apps that fit (editor, code editor, terminal, notes, reader browser, calculator, files, settings, music control), and put the "complete OS" ambition on the Linux-base track, where the same shell design becomes a Wayland compositor and the HolyC desktop runs inside it as one window, with the host services the plan already needs. That gives the user the two things they asked for without pretending one base can do both.

Conditions that change it:

• If the goal is really "a TempleOS that looks modern and runs on a PC" (an art and hobby OS, accepting no web apps, no TLS in the guest and no protection): go ZealOS, develop on x86 with KVM, skip the Linux track.
• If the user gets an x86 development host with KVM: the TCG penalty disappears and the HolyC native-app scope (including B1 layout) becomes comfortable; the base question is unchanged.
• If the user will accept a host app as the "OS" (a kiosk-style shell on macOS or Linux running the HolyC desktop and web apps side by side): the embedding option is the fastest path to a daily-driver feel, at the cost of not being an OS.

4. Long-term roadmap to a complete operating system#

4.1 Capability map#

4.2 Phases#

Where TempleOS stops being viable: at memory protection, users and processes (never), USB and modern hardware (P7 at best with months of driver work), TLS and a web platform (never in the guest), audio decoding and video (never), IME and complex text (host only). Everything from P0 to P6 is viable and worth doing as the showcase; P7 is the decision point about real hardware; P8 is the only route to the stated long-term goal.

5. Ten changes to the plan, in priority order#

6. Evidence index#

Local files read today (all [V]): README.md; docs/holyc-native-apps-plan.md; docs/core-apps-plan.md; docs/os-foundation-plan.md; docs/kosmos-app-port-research.md; docs/electron-tauri-support-research.md; desk3/01-core.HC to 05-run.HC; spike/KsSpike.HC; scripts/boot-vm.sh, send-to-vm.sh, serial-send.py, snap.sh, run.sh.

Web sources, accessed 2026-10-27:

• TempleOS Kernel/KUtils.HC (archive branch): MemCpy uses REP_MOVSB, MemSetU32 uses REP_STOSD, no SSE or MMX in the file. https://raw.githubusercontent.com/cia-foundation/TempleOS/archive/Kernel/KUtils.HC [V]
• TempleOS Compiler/OpCodes.DD: no SSE or SSE2 opcodes (no MOVDQU, MOVAPS, PADDB, PXOR and so on); XMM registers declared but unused; F64 is x87 (FLD, FADD, FMUL, FSQRT). https://raw.githubusercontent.com/cia-foundation/TempleOS/archive/Compiler/OpCodes.DD [V]
• TempleOS Kernel/KTask.HC: Spawn(..., I64 target_cpu=-1 ...), "-1 for current CPU", SpawnQue for other cores; mp_cnt. https://raw.githubusercontent.com/cia-foundation/TempleOS/archive/Kernel/KTask.HC [V]
• TempleOS Kernel/ directory listing (BlkDev, SerialDev, MultiProc.HC, PCIBIOS.HC present). https://api.github.com/repos/cia-foundation/TempleOS/contents/Kernel?ref=archive [V]
• QEMU include/ui/console.h: GUI_REFRESH_INTERVAL_DEFAULT 30, GUI_REFRESH_INTERVAL_IDLE 3000. https://raw.githubusercontent.com/qemu/qemu/master/include/ui/console.h [V]
• QEMU accel/tcg/tcg-all.c: MTTCG enabled by default when cc->tcg_ops->mttcg_supported and not icount; thread=multi forces it with a warning if unsupported. https://raw.githubusercontent.com/qemu/qemu/master/accel/tcg/tcg-all.c [V]
• QEMU target/i386/tcg/tcg-cpu.c: .mttcg_supported = true, .guest_default_memory_order = TCG_MO_ALL & ~TCG_MO_ST_LD. https://raw.githubusercontent.com/qemu/qemu/master/target/i386/tcg/tcg-cpu.c [V] (master; the 11.0.2 build on this Mac assumed the same [U])
• QEMU MTTCG design document. https://www.qemu.org/docs/master/devel/multi-thread-tcg.html [D]
• QEMU issue 2996 (x86 TCG regression on Apple M1 from 7.2 onward for one guest). https://gitlab.com/qemu-project/qemu/-/issues/2996 [D]
• ZealOS README: 32-bit colour VBE with variable resolutions, AHCI, network drivers and stack in development, Limine UEFI boot, public domain. https://raw.githubusercontent.com/Zeal-Operating-System/ZealOS/master/README.md [D]
• Shrine README: native TCP/IP stack (experimental) with PCnet-PCI II, serial tunnel, Wget, Pkg package manager, Mfa file transfer. https://raw.githubusercontent.com/minexew/Shrine/master/README.md [D]
• Search results on TCG x86 performance on Apple Silicon: qualitative only ("too slow to be usable" for full x86 VMs), no measured factor. https://www.cl.cam.ac.uk/teaching/2425/ECAD+Arch/aarch64-vm.html [D]

Unverified claims that matter most, in the order they should be tested: the TCG cost of rep movsb versus an unrolled loop (one measurement decides change 2); that TempleOS exposes modifier flags and key-up in ScanKey's scan code and kbd.down_bitmap; raw BlkRead/BlkWrite on a second unformatted ATA drive; that -smp 4 under MTTCG runs TempleOS's SMP code correctly on this QEMU; the RedSea on-disk layout for a host tool; ZealOS API compatibility with this desktop's HolyC.