tesoro 0.1.3
GitHub PyPI AEGS

Architecture

Ten deterministic engines behind one call. Every one of them may narrow a verdict and none may widen it, so the decision is order-independent — but the attribution is not, which is why evaluation order is part of the specification.

The decision path

authorize() amount, vendor, resource Arithmetic gate sign, magnitude, precision refused here, before any envelope is read economic treasury envelopes, headroom intent what it was sent to do policy your rules roi is it worth it risk trust earned over settlements risk pattern scoring evidence identity who is acting, and whose audit the hash chain escalation review queue eiap the economic gate narrow only APPROVE < REVIEW < ESCALATE < REJECT Verdict + attributed control which control decided, not just what Decision Record → hash-chained journal append-only; edits and reorderings detected
Arithmetic is checked first, and that ordering is normative. A negative amount satisfies every amount ≤ headroom comparison ever written, so a -$1000 request was once approved by this very layer. It is now refused before an envelope is read, and both that bug and a 30-digit overflow are permanent test vectors.

The ten engines

EngineGroupAnswers
treasuryeconomicIs there headroom in every envelope this action touches?
intenteconomicIs this what the agent was sent to do?
policyeconomicWhat do the operator's own rules say?
roieconomicIs the expected value worth the price?
trustriskHas this counterparty earned anything, over how many settlements?
riskriskDoes this action's shape score as risky?
identityevidenceWho is acting, under whose authority, and is it still valid?
auditevidenceAppend the record, and verify the chain.
escalationevidenceWhat needs a human, and how does it get to one?
eiapevidenceIs consulting an advisory model economically rational here?

No engine imports another engine's family, and none imports the runtime. Enforced by test, not convention. An engine that reached into runtime would be able to see state the decision path is not supposed to depend on, and the determinism guarantee would quietly stop holding.

Narrowing, and why widening is unreachable

Every engine returns an assessment. The final verdict is the most severe one any engine produced — so a single control can refuse, and no control can rescue an action another control refused.

That makes the verdict order-independent: run the engines in any sequence and the answer is identical. But the attributed control is not order-independent, and that asymmetry is why AEGS makes evaluation order normative and why conformance scores attribution rather than just the verdict.

A worked example of why attribution is hard. A sanctioned counterparty asks for more than the per-transaction ceiling. Both controls refuse. If attribution is “the last control that narrowed”, the answer depends on which limit happened to trip first — so a sanctions refusal could be reported as a budget problem.

The specification fixes this with dispositive controls: a finding that decides attribution whether or not it narrowed anything, and which must be declared. sanctions is the only one Tesoro declares.

Two channels, never one budget

internal tokens the agent burns thinking real USD, on your provider key exhausted mid-run → REJECT no human is in the loop of a running agent, so “pause and ask” becomes “hang” — and the tokens already spent are spent external what the agent pays out USDC, settled to a counterparty over the ceiling → REVIEW a payout is pausable. A person can look at it, and the agent can wait — so the correct answer to the same kind of breach differs
The two channels never share an envelope, and this is the reason: the same breach has a different correct response depending on which money it was. It is not tidy bookkeeping. An implementation may share a limit between channels but never an envelope, because an envelope carries consumption.

Why no model sits on the decision path

Every engine is integer arithmetic over structured values. Nothing in the decision path reads natural language, which has three consequences worth separating:

Cost

A decision costs microseconds and zero tokens. Ten runs of 3,000 decisions gave a p50 median of ~170 µs — and a 2.4× spread, so treat any single figure as a sample.

Determinism

Same inputs, same verdict, replayable from the journal. A model on the path would make the evidence unreproducible.

Prose injection

Structurally absent. There is nothing on the path that interprets language, so there is nothing to talk into anything.

That third one is the strongest property the design has, and it is worth being precise about why: the defence is not a filter. A filter can be got wrong. The attack surface does not exist. Seven injection payloads through every counterparty-controlled field produce fourteen verdicts identical to the baseline — not because the text was sanitised, but because nothing read it. The text survives verbatim in the journal, which is compatible with being inert only because nothing interprets it.

It reopens the moment a model is put on the path. Tesoro has an optional advisory model, consulted only behind an economic gate and clamped — it may tighten a verdict, never widen one. The clamp is well tested. Advisor injection itself is not tested and is recorded as an open finding.

Money never touches a float

Integer atomic units internally — USDC has 6 decimals, so 2500000 is $2.50 — with conversion once at the boundary and an explicitly specified rounding mode (half-up). Passing a float raises rather than rounding quietly. 

# both of these are $2.50
gov.authorize(amount_usd="2.50", ...)   # a decimal string
gov.authorize(amount_usd=2500000, ...)     # atomic units

gov.authorize(amount_usd=2.50, ...)        # TypeError

The rounding mode is pinned because every language's default differs and none is wrong in isolation — an implementation inheriting its own has made a decision it did not know it was making.

Evidence, and exactly what it proves

entry 1 hash₀ entry 2 hash₁ entry 3 hash₂ entry 4 hash₃ detected: editing an entry · deleting one from the middle · reordering · replay NOT detected: deleting entries off the end — any prefix of a valid chain is itself valid so an agent that was refused could delete the refusal, and verification would still say VALID truncated
Hashes are 128 bits minimum. Five places in this codebase retained 64 by writing hexdigest()[:16] independently — at 64 bits a second preimage is 2⁶⁴ work, reachable with commodity GPUs in months, which weakens edit detection directly. All hashes now route through one module so the length exists in one place.

Governor.verify_anchored() closes this against an external anchor, and bounds rather than eliminates it: anything appended since the anchor's last publication is unattested. Four outcomes, and an anchor that cannot be read reports unknown — never consistent, because otherwise anyone who can cut the verifier off from the sink can also make a truncated journal verify. The gap remains disclosed rather than fixed by default, and the fix that looks like one is worth naming: writing the chain head and length to a second file beside the journal is not an anchor, because whoever can truncate the journal can rewrite that file. Shipping it would be worse than shipping the gap, because it would make the system appear anchored.

Four states, never three

absent ≠ not-run ≠ unknown ≠ zero. These are four different answers and conflating any two of them loses information a reader needs:

StateMeansConfusing it with zero would say
absentnothing was claimed“we measured, and the answer was nothing”
not-runthe control exists and declined to answersame, and worse — it hides a gap
unknownit ran and cannot report a valuethe failure this rule exists to prevent
zeroit ran and the answer really is zero or false—

From a real defect: an unmeasured vendor history rendered as 0 made every advisor treat established counterparties as strangers. In the HTML report, an unset limit renders as absent and never as $0.00 — rendering it as zero would state the tightest possible ceiling where there is none, which is exactly inverted.

Reference

Public API

Stability tiers, what is deliberately not public, and where the document has been wrong.

api-surface.md →

CLI

Every command, every flag, and the five exit codes.

cli.md →

Advisors

Optional models, the economic gate, and why they can only ever tighten.

advisors.md →