On this page

`:core` — the contract and the client machine `dev.staage` — 1 file `dev.staage.wire` — 4 files `dev.staage.client` — 4 files `dev.staage.net` — 2 files `dev.staage.loom` — 4 files `dev.staage.license` — 4 files `dev.staage.fake` — 2 files `:daemon` — the runtime Boot, loop and the turn Store, journal, bus Tools and the catalog Delegation, workforce, verification, write children The surface and the providers The rails — `dev.staage.daemon.rail``:cli` — the reference client How the boot assembles the catalog

The engine — modules and packages

Three Gradle modules, 108 Kotlin files in the main source sets. This page is the map: what each module owns, and every package inside it with the file that holds it.

Module	Files	Owns	Depends on
`:core`	21	the wire contract (v7), the canonical codec, the client reducer + fold + transport, the scripted fake, the Loom side, the offline entitlement verifier	Kotlin stdlib
`:daemon`	82	the store, the bus, the turn loop, the tool catalog, delegation, the rails, the model adapters, the surface	`:core`, SQLite JDBC
`:cli`	5	the reference client: a terminal that steps the same `Reducer`	`:core`

`:core` — the contract and the client machine

`dev.staage` — 1 file

File	What it is
`Brand.kt`	the app's identity in two registers: `NAME = "Ståge"` (display), `ID = "staage"` (identifier)

`dev.staage.wire` — 4 files

File	What it is
`Wire.kt`	the phone ↔ host protocol as a typed artifact; `VERSION = 7`
`WireCodec.kt`	one `Wire` message ↔ one canonical JSON line
`Json.kt`	a canonical JSON model, hand-built so the codec has no dependency and no ambiguity
`Roster.kt`	the v3 frames — roster, thread creation, search, the model list

`dev.staage.client` — 4 files

File	What it is
`State.kt`	client state — the shape the reducer owns
`Reducer.kt`	the client state machine
`Fold.kt`	the settled fold — how the roster is ordered (attention first, then `activity`)
`Journal.kt`	deterministic rendering of a reducer run (the receipts' substrate)

`dev.staage.net` — 2 files

File	What it is
`MacClient.kt`	the app's transport to the host
`NdjsonStream.kt`	the read side: NDJSON lines in, `Wire` messages out

`dev.staage.loom` — 4 files

The host half of rehydrate.

File	What it is
`LaneJournal.kt`	a bounded per-lane journal with retention and eviction
`Pages.kt`	history pages — one page's rules and nothing else
`LaneFeed.kt`	the feed seam — where lane events come from
`LoomSurface.kt`	the protocol adapter that fronts the engine

`dev.staage.license` — 4 files

The offline entitlement verifier: parse, verify an Ed25519 signature, answer two facts separately.

File	What it is
`EntitlementFormat.kt`	the file format — parse only; no keys, no clock, no I/O
`Entitlement.kt`	the verifier
`Licence.kt`	the parsed payload's ten fields, as values
`Verdict.kt`	the two facts, returned separately

`dev.staage.fake` — 2 files

File	What it is
`ScriptedServer.kt`	a scripted server, in memory
`ScriptedStream.kt`	one step of a scripted stream

`:daemon` — the runtime

82 files: 70 in dev.staage.daemon, 6 in provider, 5 in rail, 1 in fake. Grouped by what they do, not by alphabet — this is the map an operator or a contributor actually needs.

Boot, loop and the turn

File	What it is
`Daemon.kt`	the daemon — store, bus, loop, surface, composed
`Loop.kt`	the loop, behind interfaces (`Provider`, `Tool`, `Approver`)
`TurnExecutor.kt`	one turn, executed: rounds, tool calls, approvals, usage
`TurnMachine.kt`	the turn executor's state machine, named
`TurnRound.kt`	one round with the provider
`TurnTools.kt`	one assistant message's tool calls, sequentially, in order
`TurnToolCalls.kt`	the opening every tool call shares — its persisted `tool_use` block
`TurnToolChoice.kt`	the tool-choice reading and the `tool_use`/`tool_result` conversation shape
`TurnBlocks.kt`	block flushing
`TurnCompaction.kt`	the request's lens — compaction as a projection of the record
`TurnSteer.kt`	steering at the safe checkpoint — the executor's half
`TurnUsage.kt` / `TurnUsageAccumulator.kt`	the turn's usage, and the sum across rounds
`Guard.kt`	the loop's airbags and its result boundary
`Continuation.kt`	continuation — the task walks
`ApprovalGate.kt`	the approval round-trip, made mechanical

Store, journal, bus

File	What it is
`Db.kt`	the one connection to our store, and the one writer
`Schema.kt`	our schema, our names, migrations from the first commit
`Store.kt`	the write paths, the read paths, and the rules
`StoreSql.kt` / `StoreRows.kt` / `Model.kt`	SQL plumbing, row mappers, the rows as values
`StoreRoles.kt`	the three roles a store can play, and the one guard between them
`JournalStore.kt`	appends one lane event; the ordinal is the lane's durable order
`MessageStore.kt`	append one steering sentence to a running turn
`ToolCallStore.kt`	the tool-call rows
`BlobStore.kt`	put one picture into the store, answer the name it earned
`Search.kt`	server-side search over our store
`LaneBus.kt`	our bus — the in-process fan-out
`EventRecorder.kt`	persistence and fan-out, in that order
`Spool.kt`	the runtime spool files — a stable floor, never the system temp dir
`Clock.kt`	time, injected
`Digest.kt`	a deterministic digest, in one place
`Activity.kt`	the daemon-global monotonic counter the roster reads

Tools and the catalog

File	What it is
`Toolset.kt`	the tool registry — the single declaration of what the model may call
`Tools.kt`	the v1 toolset (`scratch_read`)
`FileTools.kt` / `FileState.kt` / `FileModes.kt`	`file_read`, `file_edit`, `file_write` — the sealed outcome vocabulary, the modes
`FindTools.kt` / `FileLocate.kt`	`file_find`, `file_search` — the locating mechanics both share
`SkillTools.kt`	the skills mechanism — know-how cards listed and loaded on demand
`Bash.kt`	run one shell command — the resident's own command line
`BashSandbox.kt`	the box a `bash` command runs in — a value, not a second code path
`DevCheck.kt`	run one gate and read the result
`Plan.kt`	the plan — the turn's spine, declared by the agent and read by the human
`Workdesk.kt`	the desk — the thread's workdesk page
`EffectClass.kt`	what a tool does to the world — the class the approval decision reads
`ToolProfile.kt`	the turn's tool profile: which declared tools this turn may use
`EnvScrub.kt`	credential-shaped variables, removed by shape rather than by name
`TokenBoundary.kt`	the bearer is not workspace-readable
`Workspace.kt`	the workspace root — one directory the file instruments may touch
`Compact.kt`	compaction — the request is a projection of the record
`Senses.kt`	the Senses — a local, opt-in record of what this daemon actually did
`StandIn.kt`	the stand-in — what answers when no client does
`Steer.kt`	steering — the human's hand lands at a checkpoint, not between two wires

Delegation, workforce, verification, write children

File	What it is
`Delegation.kt`	delegation — a child is a contract, not a transcript
`Deck.kt`	the deck — the waiting room between a child that cannot move without its parent
`Workers.kt` / `WorkerModels.kt` / `WorkerRules.kt`	the workforce as one pure state machine: statuses, budgets, typed outcomes, and one boolean per rule
`Verification.kt` / `Verifier.kt`	verification — a verifier reads the artifact, not the builder; one verifier child per `task.verify`
`WriteChild.kt` / `WriteSession.kt` / `WriteTools.kt`	the write child: a disposable worktree, a diff with a digest, and `apply_change` as the one writer
`Worktrees.kt`	the process seam — one child, one disposable checkout

The surface and the providers

File	What it is
`DaemonSurface.kt`	the wire, served by our daemon
`Models.kt`	what this daemon can run, and whether it may
`provider/Sse.kt`	the transport seam, and the one stream engine both adapters sit on
`provider/Anthropic.kt`	Anthropic's SSE event flow
`provider/OpenAiCompat.kt`	the OpenAI-compatible Chat Completions API — the generalization test
`provider/Wire.kt`	the provider-agnostic vocabulary the adapters share
`provider/Targets.kt`	the builder's provider, chosen from the environment's credentials
`provider/Replay.kt`	the recorded-stream transport (the gates' world, no network)
`fake/Scripted.kt`	the scripted brain

The rails — `dev.staage.daemon.rail`

File	What it is
`Rail.kt`	the rail seam — one request/response read, as a value
`Rails.kt`	the rails as shipped: what the model is shown, and what the environment enables
`Bank.kt`	the knowledge rail — read-only search and fetch over the user's own posts (`bank_search`, `bank_get`)
`Librarian.kt`	the librarian — one approved read that hunts the store from several angles (`librarian`)
`Research.kt`	the research rail — one live question answered from the open web (`research`)

A rail is offered only when it can answer. Every rail needs a credential; a rail whose credential is absent is not declared at all, because a tool the model can see and cannot use is a trap — the model calls it, the human is asked to approve a call that cannot succeed, and the turn burns a round trip to learn something boot already knew. The daemon prints which rails are offered and, for each that is not, the variable that would enable it; --require-rails turns that report into a refusal.

`:cli` — the reference client

5 files.

File	What it is
`Command.kt`	the command language — pure syntax
`Session.kt`	the session: the client, the reducer, the honest refusals
`Repl.kt`	the command interpreter
`Renderer.kt`	rendering — the honest face of the machine
`Main.kt`	options and the one entry point

The CLI is not a demo. It is the CLI-testable maxima: every UI claim the phone makes is provable off-screen first, because the terminal steps the same Reducer the phone steps.

How the boot assembles the catalog

script/daemon-run/StaageDaemon.kt is the only place the toolset is composed, and it is composed from declarations — never from a mutable map:

val toolset = Toolset.of(
    listOf(V1Tools.scratchRead(scratch)) +
        FileTools.declarations(workspace) +
        FindTools.declarations(workspace) +
        SkillTools.declarations(skills) +
        Bash.declaration(workspace, bashSandbox) +
        listOf(Plan.declaration()) +
        listOf(Workdesk.declaration(store, clock)) +
        (delegateHolder?.let { listOf(Delegation.declaration()) } ?: emptyList()) +
        (writeApplyHolder?.let { listOf(WriteApply.declaration(it)) } ?: emptyList()) +
        rails.declarations(),
)

Toolset keeps catalog (what the provider renders) and tools (what the loop dispatches to) as two projections of one list — they cannot drift. Names are host-assigned and collision-free, and each descriptor is pinned by digest of (origin, raw name, schema), so a material change is a different tool and an approval can be bound to it. See The tool catalog.

Generated from docs/ in the Ståge repository. Markdown is the source; this page is a rendering of it.

The engine — modules and packages

:core — the contract and the client machine

dev.staage — 1 file

dev.staage.wire — 4 files

dev.staage.client — 4 files

dev.staage.net — 2 files

dev.staage.loom — 4 files

dev.staage.license — 4 files

dev.staage.fake — 2 files

:daemon — the runtime