thurbox-kernel

Thurbox plugin kernel and plugin authoring

Working reference extracted from CLAUDE.md, which indexes it. The rationale behind these decisions is owned by the docs under docs/; a change that invalidates what this says updates it in the same PR.

Architecture (plugin kernel)

The interface is Lua running on a Rust kernel. thurbox boots the kernel, which reads ui/ and renders whatever plugins it finds; there is no built-in pane. v1's src/app (TEA model/update/view) and src/ui (35 render modules) were deleted when the kernel took the binary name — v1 lives on the v1.x branch.

The five rules

1. Four node kinds, forever — text, box, input, surface. Everything else composes in ui/lib/widgets.lua. tests/kernel_mvp.rs asserts the count.
2. Layout resolves before render — rects are computed first, then each plugin is called with its own. Plugins declare size statically, in their declaration table, which is what breaks the circularity.
3. Snapshot-read, command-write — reads come from an in-memory snapshot and return instantly; writes are commands accepted now and surfaced later. Lua never blocks, so no plugin can stall the loop on SQLite, git or an unreachable host.
4. Capabilities by absence — an ungranted capability is not in the environment. io, os, debug, package and the loaders are withheld, and thurbox.yml makes selene enforce that statically. One capability cannot be expressed that way: a program pane is asked for through command, which every plugin has, so thurbox.granted reports the grant instead — a boolean about a decision already made, which withholds nothing.
5. Anything touching the world runs on a worker — terminal attach, commands, diffs, metrics, git stats, repository reads, update checks, and programs a plugin asked for.

Module Dependency Rules (enforced by tests/architecture_rules.rs)

session  ← pure data types, no crate-internal references
agent    ← session (+ paths/shell utils; NEVER git)
kernel   ← session + storage + sync + paths + session_ops + git
           (+ agent/usage by fully-qualified path only)
main     ← the coordinator: the loop, the workers, the chrome