Crate yog 

The yog server — the standalone engine of the four-component split (REMOTE §12): holder of the world, the balls and the conversations, with no UI and no local execution.

One world, one engine. The binary boots engine::Engine, which derives every workspace from disk, answers the §8.5 control boundary over the REMOTE §9.5 wire, and drives litany/bl/bz as children of the nested world. Every seat — the lernie window, an android client, a yog gesture from an agent’s own bash — is a client of that boundary and of nothing else; yog paints nothing (bl-7942 severed the egui face into its own crate, REMOTE §8).

docs/DESIGN.md is the authority for the state inventory, the attention model, and the module map; the module docs below stay terse and defer to it. The shape in brief: app holds the AppModel and its per-tick derivation over the pure view-model modules — git_tree, the nav roster, attention, projects/binding, start, ui_state, and the inspector projections (transcript, steps_view, inboxview, budgets) — and boundary is the one surface every act and every read crosses, serialized by each module’s own wire. cli_outbound execs the binaries; actions holds the message/stop/scan/close/unclaim/create/update verb surface; delete the §3.6 unmaking; badge is what is left of the palette — the words a derived row says, never a colour.

The crate root is deliberately declaration-only. A root carrying a coverable impl or fn accrues an llvm-cov phantom uncovered region on its header line each time the pub mod list above it grows and shifts byte offsets (this cost 99.90% coverage after the Y2/Y7/Y15 folds). With all coverable code in submodules, new pub mod lines have no root-level line to mis-attribute, so coverage stays at 100% as modules land.

Re-exports

pub use app::AppModel;

pub use app::Args;

pub use app::Roots;

Modules

actions

User actions issued through cli_outbound (ARCH §3.4 / §3.5).

alert

The §6 attention strip escalated to the desktop (bl-e160) — what a decision queue row becomes when the window is buried, and the one spawn that says it. The attention strip, escalated to the desktop (DESIGN §6 as amended, bl-e160). §6 is yog’s core promise — does anything need me? — and it is invisible whenever the window is buried or minimized. When a new thing needs you and you are not looking at yog, the desktop says so.

app

Top-level app state and the render entry points.

attention

The attention model (DESIGN §6, §15 Y10): the derived per-agent predicate, its per-signal detail for badges, the workspace/strip rollups, the jump-to-next-attention control, and the roster sort.

badge

What a derived row says about a fact — the badge vocabulary that is all a server keeps of the §11 palette (bl-7942). The badge vocabulary — a glyph and the fact said in words, together, in one home per fact.

binding

Workspace enumeration across the three roots (DESIGN §3.1). Everything here is a pure function of injected roots plus a bounded directory walk — no env reads (roots come from crate::xdg), no writes.

board

The V4 board (VISION §5 V4, DESIGN §11): the balls section as columns.

boundary

The control boundary (VISION §4.8, DESIGN §8.5): the one typed surface every operator gesture crosses.

budgets

Whole-tree budget-spend fold (DESIGN §5.1 #16; ARCH §6 budgets).

cli_outbound

CLI outbound: the frontend’s sole command surface to the harness. Every user action is an exec(<binary>, args) and nothing else (ARCH §3.4/§3.5; “resume” is no longer user-facing per the §2.9 amendment, bl-abf3).

config_edit

Config-editing view-models (DESIGN §9): load → edit a RAM draft → Apply = stage → (validate, where a validator exists) → hash-guard → atomic rename.

context

How full a conversation’s context is (§5.1 #35) — the latest step’s prompt against the window models.yaml declares. Fullness, not spend. How full is this conversation’s context? (DESIGN §5.1 #35, §11’s settings rows.) The context-window percentage is shown per chat.

control

The capability control (§8.6, VISION §4.11) — the adjudicator litany’s tool-control seam consults before every granted tool invocation. The capability control (VISION §4.11, DESIGN §8.6): the executable litany’s tool-control seam consults before every granted tool invocation executes, and everything it reads to answer.

delete

Workspace deletion — the §3.6 unmaking (DESIGN §3.6, the §8.1 planner idiom, the §8.2 verb row).

engine

The one assembly a bare yog boots (VISION §5 V5) — model, worker, bridge, gesture consumer, monitor sentry, fleet pilot and the wire listener. The engine both faces run (VISION §5 V5.1, DESIGN §8.5): the model, the derivation worker, the watch bridge and the gesture consumer, assembled once from a composed world.

fan

The VISION §4.10 mutating fan — N isolated candidate attempts over one delivery obligation, materialized through balls’ attempt capability. The mutating fan — N ≥ 1 isolated delivery attempts over one delivery obligation (VISION §4.10, bl-2b8c; DESIGN §3.8).

files_view

Agent-worktree file view-model (DESIGN §11 Altitude-2 Files tab).

fixture

Named deterministic world states a client harness can dial and render (bl-8741) — the fixture roster, its writer and the yog fixture verb. Fixture worlds (bl-8741): named, deterministic world states an external client harness can dial and render.

fleet

The VISION §4.3 armed loop — off until the operator arms it per workspace. The armed loop (VISION §4.3, story rung V4 item 2): the backend’s own level-triggered pass that brings a workspace’s drone count to match ready work under a policy cap, and reaps by comparison.

fork

The attempt — one fork of a conversation from one point in its history (VISION §5 V2, the Counterfactualist rung; DESIGN §5.1 #32, §11 rail).

fs_watcher

Filesystem watcher for a watched root.

git_env

The ambient-git-environment scrub: one list, one constructor, every child.

git_tree

Git-tree view-model (ARCH §7.1 live view, §3.5 agent-state contract).

inboxview

Inbox deposit view-model (DESIGN §11 Inbox tab; ARCH §2.11 deposit).

login

The login flow (DESIGN §8.3 as amended, §15 M6 Z8): bz’s one interactive surface, run as the streamed-piped spawn class (§8’s third class). bz --login --provider <row> --browser streams its sign-in lines live to the invoking surface — the Login pane, and beside an auth-failed step — verbatim (§5.3 instance-local RAM); on exit ONE outcome row lands in ops.jsonl (§4.2, the stream never logged line-by-line), and a non-zero exit carries the exact command as a run-by-hand fallback (§8.3). Credentials stay bz’s: yog renders the flow, never reads or writes a credential (§5.1 #22).

model_pick

The model picker (DESIGN §9.4) — the pure half.

monitor

The alignment monitor (VISION §4.9, story rung V6): a second, cheaper model reads what an agent is doing and answers one question — does the recent work serve the stated goal?

multiplex

The self-multiplex spine (DESIGN §16.7 W12). yog’s own executable is the physical target of every embedded-tool spawn: a litany/bl/bz leading verb — yog litany <argv…>, yog bl <argv…>, yog bz <argv…> — dispatches here, to the arm that calls the embedded crate’s entrypoint exactly as each upstream’s own thin bin does (all three filled: W8/W10/W11), and so do balls’ two sibling plugin binaries — yog bl-delivery <op> <phase>, yog bl-tracker <op> <phase> (bl-2930, the U-balls-3 seam) — spawned by the embedded balls’ own plugin chain through the world/tools/ shims a yog bl prime binds. Everything else — no args, --editor-apply, yog env/yog exec, the GUI — is not a namespace and falls through (dispatch returns None).

names

Workspace names (§3.1) — the one name altitude yog still owns.

naming

Wire names (REMOTE §8, bl-f5f6): how a workspace or a project is addressed when a path may not cross the boundary.

nav

The altitude-0 navigator view-models (DESIGN §11): the workspace tab bar (tabs) and the focused workspace’s conversation list (convs), the §11 context-menu seat roster (menu), plus the shared row/key types. No egui and no git/ui_state dependency: the caller (AppModel) derives the input facts from the snapshot map + attention + the §3.5 join, and the shell renders the outputs. Every branch is table-tested with plain data.

opslog

ops.jsonl: the durable action-outcome log (DESIGN §4.2, §15 Y15).

projects

Project (balls-clone) enumeration and nested-delivery detection (DESIGN §5.1 #1, §15 Y14).

rail

The step spine — every operable commit a conversation has, and what hangs off each one (VISION V1, the Historian rung; DESIGN §11).

registry

The REMOTE §4 client registry (bl-8bbc): who participates in which workspace, and each client’s own per-seat home. The client registry (REMOTE §1.5, §2, §4, §7; bl-8bbc): the durable server-side fact that client C participates in workspace W, and the per-client home everything else about C hangs off.

science

The §3.9 attempt science projection (VISION §4.10 item 7): one derived row per delivery attempt, joining frozen inputs, refs, usage and outcome. The attempt science projection — one derived row per delivery attempt (VISION §4.10 item 7, bl-40ab; DESIGN §3.9).

search

Global search (DESIGN §8.5): one derived query over the world’s own bytes, and the §8.5 boundary’s only asynchronous one.

spend

Spend attribution: the yog-side join (DESIGN §3.5; VISION spend attribution).

start

The composite “start a conversation” verb (DESIGN §3.4, §8.1, §15 M6 Z3): a pure planner + a step executor, the one flow that turns Enter-in-a-box into a running litany loop.

state

The crate’s lock chokepoint (Bootstrap rule 7): the cross-thread shared-mutable-state locks live in this one file, so the whole-crate shared-state inventory is auditable in one place. rules/locks-outside-state.yml enforces the confinement; the only carve-outs are test scaffolding and one documented exception, git_tree::probe_cache — the macOS TTL cache’s Mutex is single-thread interior mutability local to the probe stack, not cross-thread shared state, and a generic decorator folded in here would break llvm-cov’s per-line coverage (see that module’s doc).

steps_view

Per-agent steps inspector view-model (DESIGN §11 Altitude-2 Steps tab; §5.1 #13; §15 Y13). Milestone M2’s last piece: browse every byte.

tool_host

yog’s litany tool injection (REMOTE §5, bl-c907) — the clients tool, the agent’s durable loaded set, and the router the executor consults. yog’s tool injection (REMOTE §5, bl-c907): the object the yog litany arm hands litany at Fx::tool_injection, so an agent can see this workspace’s client machines and drive the tools they advertise.

transcript

Transcript view-model (DESIGN §5.1 #12, §11 Altitude-2 Transcript tab).

ui_state

yog’s converging UI state (DESIGN §4.1, §15 Y8) — the four attention seen watermarks, pinned, identity_last_used, ceiling, prices, and the pane’s own panels / collapsed / knobs ([knobs]: the §11 transcript-density automatics, the zoom, the §6 escalation).

watch

Watch registry + repaint bridge (DESIGN §7.2, §15 Y6).

wire

The client/server wire (REMOTE §9.5, bl-b6fa) — the engine’s mTLS listener, a seat’s transport, and the framing between them. The wire (REMOTE §9 step 5, bl-b6fa): the mTLS channel a seat reaches the control boundary over, and the transport a seat is made of.

workdiff

What the agent actually changed — the project work-diff (DESIGN §5.1 #32, §11 Altitude-2 Work tab; VISION §4.10, bl-2b8c).

world

The nested world yog composes under its own data root (DESIGN §16.2) — the pure ambient Env → world Env composition plus the <yog-data-root>/world/ subtree layout. yog reads the ambient environment once, anchors on $XDG_DATA_HOME/yog, and layers a fixed three-var override set over that snapshot; the composed result is itself an Env, so every §5.1 fold re-derives the nested location through it (balls state, litany home, and yog’s own ui.json/ops.jsonl). Brazen’s three folds are not here and not ambient: since the blast-radius ruling they resolve inside the focused workspace’s wall, one layer further in (wall). This module is the pure composition layer only — it neither materializes the subtree nor wires the world into any spawn (W2/W3); the submodules do the effectful halves (seed the litany home, tools the agent-tool shims).

xdg

The one home for every filesystem-path derivation in yog (DESIGN §15 Y2, §5.1). Balls, litany and yog locate their state through XDG folds; this module reproduces each fold once, over an injected Env snapshot — except balls’, which is no longer reproduced at all: the crate is linked (§16.7 W8), so Env::balls_layout hands back balls’ own layout::Xdg and every balls path derives from it.