Architecture — how it is built

One Rust binary (~3 MB, built small with strip + lto + opt-level="z"). No extra runtime. Only a few libraries: clap, serde, ureq, sha2, toml, regex.

01HOW IT RUNS

┌─ kineti CLI ──────────────┐      ┌─ kinetid (`kineti serve`) ──────┐
│ steps 1–13              │ UDS  │ shared spend counter          │
│ model loop · file checks │◄────►│ saved log pointers            │
│ input screening · checks .sock  │ .kineti/kineti.sock (mode 0600) │
│ test tie · undo · log    0600  └────────────────────────────────┘
└───────────────────────────┘
        │ same code runs with or without daemon
        ▼
   model providers over HTTPS (OpenAI format)

Daemon. kinetid keeps the shared spend count and saved log pointers. Writes are O(1). Many CLI runs can share one spend counter. Warm calls take tens of microseconds. If no daemon is running, every command runs directly — same code either way, proven identical by CI. Full history check is not in the fast path; it still must pass at the ship gate and kineti verify --all. Without the daemon, parallel runs use a file lock and stop rather than race.

02MONEY CHECK — RESERVE THEN SETTLE

Each model call reserves an estimate before the request and settles the true cost after. This uses an atomic micro-dollar counter. Even with many workers, the total cannot go over. Limits are checked at settle: whole run, each stage, each worker. Over any limit stops the run. To resume, you must create .kineti/spend.reset by hand.

STEP	WHAT HAPPENS
reserve	Estimate tokens × price → take from counter before the request
call	Provider replies with true token counts
settle	Refund if estimate was high, or take more if low. Check all limits.
halt	Over limit → stop between stages. Only `.kineti/spend.reset` resumes.

03SAVED HISTORY — LINKED LOG

.kineti/journal.jsonl saves each action as a typed record linked by cause edges (caused · triggers · blocks · enables · …). Each link is checked for loops and time order before saving. Records age active → warm → cold → archive. Nothing is deleted.

Each swarm worker writes its own log (journal.w-<task>.jsonl). After merge, workers' logs are joined to the main log with a two-parent merge record. Check is by branch name: kineti verify --all checks every branch, names the branch if a byte was changed, and blocks ship if any branch is orphaned or was extended after merge.

04INPUT SAFETY STEPS

Six steps between the model and the system:

Trim input — cut to the allowed character limit.
Mark tool output as data — lines that look like instructions are set aside, not run.
Check shape and range — validate what was seen before deciding.
Raise signals — show odd cases instead of hiding them.
Limit tools by step — only the tools allowed for this step exist. Read-only until spec is approved.
Lock to folder — every tool can only touch the project folder.

05USE FROM OTHER CODE

The same binary builds as libkineti with a safe C interface — see C API. Errors come back as ok=false plus text. A panic never crosses the boundary.

06STARTUP

CI checks startup time (tests/perf_startup.rs) and binary size (scripts/size-gate.sh). Fast-path flags skip work before the main command list is even built.

Next: Security · C API · Governance