Verdict / Decisions
Engineering decisions
Verdict records significant choices as append-only decision records: context, decision, and consequences. These nine explain most of how the system behaves. The full index is in the repository.
Decide before ranking
Deterministic policy and transition graphs
- Decision
- A versioned hard-policy document compiles before any ranking or execution. Each candidate resolves to allow, deny, or unknown, and only allow enters ranking. Retries and fallbacks form an inspectable graph; after the first response bytes, switching to a different route is forbidden.
- Trade-off
- Mid-stream failover is given up so that one response never splices output from two models. Stale evidence may be used only for unprotected work, and only when explicitly enabled.
Fail-closed capability passports
- Decision
- Qualification is a versioned passport for one exact route: gateway, provider, endpoint, protocol, and upstream model. A hard requirement is satisfied only by a fresh observed
supportedvalue, and a fresh negative observation beats a conflicting claim. - Trade-off
- Catalog metadata stays useful as provenance but never grants permission to execute, and an alias cannot merge two distinct routes. The passport is deliberately not a probe scheduler or a signed attestation.
Observed free status and context omissions
- Decision
- Free status is
free,paid, orUNKNOWN, never inferred from a missing price. A context source that was requested but could not be read is recorded with a reason instead of being silently skipped. - Trade-off
- Preferring free models is a ranking, not an exclusion, so a gateway that publishes no pricing is not locked out. Cost figures remain estimates.
Core owns model metadata
- Decision
- Capabilities come from a Core-owned store fetched from models.dev and LiteLLM's published data, with a source and fetch time on every field. The gateway is limited to inventory, execution, and health.
- Trade-off
- A model is dropped until it is explicitly mapped. Expanding coverage is a data change, not a heuristic, and missing leaderboard scores stay empty rather than estimated.
Evidence and learning
Evidence authority and portable receipts
- Decision
- Evidence is labeled claimed, observed, verified, or inferred. Only a fresh direct observation admits a hard capability. Receipts are append-only metadata envelopes; raw prompts, completions, and credentials are rejected at the boundary.
- Trade-off
- Authority is provenance, not permission. Claims and scores can explain a decision but cannot turn unknown into supported, so some usable models wait until they are observed.
Shadow and counterfactual evaluation
- Decision
- Advisory learning runs in shadow. Promotion requires a durably recorded, integrity-checked report bound to an exact route and a fresh passport, and counterfactual results are replay-only.
- Trade-off
- Improvement is slower: a better-scoring route is not promoted until verified evidence supports it, and operational failures are never counted as quality evidence.
Boundaries with other systems
Proof-carrying decision plane
- Decision
- Verdict owns the chain from bounded context to eligibility, decision, receipt, and proof. Gateways and LiteLLM are optional adapters, and the UI follows the receipt contract.
- Trade-off
- Rejected alternatives: a separate decision-plane repository, a new unified memory database, letting a gateway own the decision, and building the UI before the proof slice. Each would have split the source of truth.
How the work gets done
Project-owned Prime workflow
- Decision
- Five workflow skills own resumption, hydration, dispatch, proof, and finishing. Linear owns objectives, GitHub owns source and merge facts, and local checkpoints are hints reconciled with both on every restart.
- Trade-off
- External Linear, GitHub, and model health remain runtime prerequisites. A legacy session that was already running is not retroactively fenced.
Governed swarm supervision
- Decision
- Swarm supervision was originally part of Core. It was later removed, and dispatch moved behind a single execution-path authority.
- Trade-off
- Kept as a record, not deleted. Decisions are superseded rather than rewritten, so the reasoning behind the old design stays reviewable.
Sources
Primary material in the public Verdict repository.