Engineering Principles

The design rules behind stella — determinism over intelligence, evidence over opinion, an engine with no I/O of its own, and spend limits enforced at safe points.

stella ships two research papers alongside its code: a study of seven architectural rules and a closer look at the deterministic engine. Here are the principles behind stella, and why they were chosen. Every claim below matches what actually ships.

"Witnessed, not asserted" describes the path you choose, not the program itself. The witness-test and flip-check machinery described below, and the "Is the work done?" and "What proves the change?" mechanisms, are things an installed verification plugin implements on its own side of the wrapper socket. Oxagen's Vera is the reference plugin. A plugin reports its own evidence, and stella checks that evidence against the rule the plugin set up at install time. stella never re-runs the check itself. A plain stella run with no --pipeline <variant> has nothing verifying it, and it tells you that instead of implying otherwise.

The master rule

When stella can decide something with a plain mechanism or a model's judgment, it uses the mechanism, and saves the model for the places only intelligence can handle. The full argument has the research behind it. Here's the shape of it:

  • A plain check is reproducible. It gives the same answer on the same input tomorrow, in CI, and on a coworker's machine. A model's opinion is just one sample.
  • A plain check is auditable. When it fails, you can read exactly why. A model's verdict has to be checked itself before you can trust it.
  • A plain check is free. No tokens, no delay, no rate limit.

You can see the rule everywhere in the product:

Is the work done?

Mechanism: the flip oracle — a test that fails before the change and passes after — plus a guard against empty diffs and a 400-line diff budget.

Model, as fallback: none. When the evidence doesn't add up, stella reports Unverified instead of guessing. (Goal mode's verifier is different: it runs every round, always, and it's never a fallback for unclear evidence.)

What proves the change?

Mechanism: the witness step runs the witness test against the code before your change. It has to fail there and pass after.

Model, as fallback: none. A test suite that's simply green is weak evidence, never proof, no matter who says otherwise.

Which model serves a role?

Mechanism: you pin a model explicitly, or explicitly set none. There's no hidden "auto" string doing something unclear.

Model, as fallback: auto_mode picks from your allowed_models list, using clear rules: a different model family first, then price tier, then list order.

What goes in the prompt?

Mechanism: a system prompt that never changes byte-for-byte, plus one fixed-position block for recalled context, so prompt caching keeps working across turns.

Model, as fallback: none.

When does a run stop?

Mechanism: a spend guard, checked between steps, never in the middle of a tool call. That means stopping never leaves a half-finished edit.

Model, as fallback: none.

What happened?

Mechanism: an append-only event log and local SQLite records you can query yourself.

Model, as fallback: none.

Two of these are one command away, and they aren't just plans on paper. They're what you're already using:

# The flip oracle, armed: a run that cannot prove fail→pass does not submit.
stella run --pipeline my-verifier --test-command "cargo test -p stella-core" \
  "fix the witness tamper check"

# The ledgers, read back — no model involved, no network, no key.
stella stats

The seven rules

  1. Ports, not direct dependencies. Every provider and tool sits behind a shared interface. Adding a new one is an adapter, never a rewrite. Nine providers plus any local server, one engine.
  2. No I/O in the engine. stella-core does no reading or writing of its own. Routing, retries, trimming context, loop detection, and spend limits are all plain functions over data it already owns. That makes them testable, with no network and no filesystem needed.
  3. The witness-test contract. An agent has to prove its change actually fixed the problem: fail before the change, pass after it, with tampering ruled out. "The test suite is green" is not proof on its own. An installed verification plugin (Vera is the reference one) runs this check and reports the result.
  4. Bring your own key, and no telemetry leaves your machine by default. Your keys talk to your provider directly, and by default all telemetry stays in a local SQLite file. Exactly two setups send telemetry anywhere, and only these two: Oxagen Enterprise enrollment — a signed policy, no runaway processes, a closed and content-free summary, and one exact allowed HTTPS destination — and a drain block in ~/.stella/cloud.json that stella cloud sync sends to. Neither one exists until you set it up.
  5. Memory built for prompt caching. Durable knowledge loads once into a prefix that never changes byte-for-byte, and rides the cache at about a tenth of the cost. See No invalidation.
  6. Spend limits enforced at safe points. --spend-limit is a hard cap checked between steps, so stopping is always clean and never leaves a half-finished edit.
  7. An open standard for pulling in context. Context recall uses the Context Graph Protocol: versioned wire types, automatic conformance checks, and a clear trust model.

No single rule here is the advantage. The combination is. Each one constrains the others: you can't bolt cache-friendly memory onto a system that re-sends everything each turn, or witness verification onto an engine that can't replay the same way twice.

What this gets you

  • Trust: "done" means witnessed, not asserted. It's reported by an installed verification plugin and checked against the rule that plugin declared.
  • Reasoning you can follow: one single-threaded loop, readable top to bottom. No coordinator, no hidden control layer, no swarm state to fall out of sync.
  • Cost: the caching discipline and the evidence checks mean you pay for a model's judgment only where a model's judgment is the only tool that works.
  • You stay in control: state lives on your machine first, credentials are yours, the license keeps the source open, and no telemetry leaves by default. Both ways telemetry can leave — the Enterprise export and the cloud.json drain — are explicit, limited, and off until you configure them. The Enterprise path is also content-free and controlled by your organization's enrollment.

Continue: Why one thread beats a swarm → · No agent overwrites another's work → · A session is an artifact, not a service →

Diagnostics

How to turn on logging, read the crash file, and safely share a log with -v, --log-level, and --log-file.

Determinism over intelligence

Why stella runs one deterministic thread instead of a swarm of agents, what research on multi-agent failures found, and what that means for how it works.