Bring your own judge

Why this exists

Most serious systems already know how they want to judge their own work. Spoolis is useful when that result needs to leave the system and be trusted somewhere else: by billing, a deploy pipeline, a retry workflow, a marketplace, or another agent.

The flow is always the same:

your evaluator → signed or structured result → Spoolis → portable Outcome → billing / runtime / deploy / marketplace / another agent

Spoolis records which evaluator produced the result, binds it to the agreement and evidence, preserves partial, uncertain, and earned value, and signs the Outcome so any number of downstream consumers can verify it independently.

Declare the judge on a condition

A condition judged outside Spoolis uses verification_method: "third_party" with an external_judge declaration. The declaration names the evaluator, its kind (buyer_owned, marketplace_evaluator, external_service, ai_evaluator, zk_verifier, or human_arbitration), and the proof requirement: signed (with the evaluator's public key), hashed_ref, or declared.

{
  "description": "Billing telemetry stays within the agreed error threshold",
  "required": true,
  "verification_method": "third_party",
  "external_judge": {
    "evaluator_id": "acme-billing-telemetry",
    "kind": "buyer_owned",
    "proof_requirement": "signed",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
  }
}

The evaluator's result arrives as evidence with provenance: "external_tool_result" carrying the result object: the verdict, per-condition rows, optional per-unit verdicts, and the proof. With proof_requirement: "signed", Spoolis verifies the signature over the canonical result payload and refuses to bind an unverified result to the Outcome; it degrades to uncertain, never to a silent pass.

Example A: coding agent with CI and buyer-owned telemetry

Agreement: migration complete, tests pass, billing stays healthy. Judges: CI for the tests, the buyer's own telemetry check for billing. If CI passes but the telemetry condition fails, the Outcome is partial or fail, the deploy consumer refuses to proceed, and a remediation agent receives exactly the failed condition.

The consumers gate with requireOutcome:

import { requireOutcome } from '@spoolis/receipt-verifier'

const gate = await requireOutcome(receipt, {
  minimum_status: 'pass',
  evidence_requirements: 'satisfied',
}, { trustSet, environment: 'production' })

if (!gate.ok) {
  // gate.reasons names why; the receipt's condition_results name
  // which condition failed, so remediation gets a precise target.
  blockDeploy(gate.reasons)
}

Example B: marketplace evaluator, 8 of 10 units

The marketplace keeps its evaluator. It submits per-unit verdicts; Spoolis standardizes the result: 8 accepted, 2 rejected, $8.00 earned, signed. Billing pays what was earned, and the workflow retries the rejected units. A partial batch has result: "partial", so a consumer that should act on it gates on units and money, not on minimum_status: "pass":

const billing = await requireOutcome(receipt, {
  minimum_status: 'partial',
  min_accepted_units: 1,
}, { trustSet })

if (billing.ok) payExactly(billing.earned) // '8.00'

This is live: the two-consumer demo receipt shows one marketplace-judged Outcome consumed independently by a billing system and a retry workflow, with both consumption events recorded on the public page.

Example C: prerequisite results for a consequential action

An agent runtime can require prerequisites before a consequential action: the fee is known, the terms were retrieved, an explicit confirmation exists where policy requires one. If the runtime chooses to use Spoolis as the result layer, each prerequisite becomes a condition, the runtime's own checks judge them, and the signed Outcome records whether they were satisfied at decision time.

Spoolis does not own user intent or authorization. It records whether declared prerequisites held, for the runtime and for anything auditing the action later.

The trust boundary

Spoolis proves: which evaluator produced the result, what agreement and evidence it was bound to, what verdict was signed, and how earned value was derived. Spoolis does not prove the external judge was substantively correct, or that every outside-world fact was true. The public receipt page states this boundary on every Outcome, and consumers should read condition_results[].method and the evaluator identity before deciding how much weight to give a verdict.

Calling it

Everything above works over the plain HTTP API, the hosted MCP (anonymous sandbox needs no account), and the SDKs. The quickstart covers the create, evidence, verify sequence; the sandbox scenario external_judge_two_consumers runs the whole marketplace example end to end in one call.

curl -X POST https://spoolis.com/api/sandbox/scenarios/run \
  -H "authorization: Bearer $SANDBOX_TOKEN" \
  -H "content-type: application/json" \
  -d '{"scenario": "external_judge_two_consumers"}'

What to use this for

• Cross-system handoffs, where the judging system and the acting system are different.
• Partial results and earned value that a boolean would destroy.
• Multiple independent consumers of one judgment.
• Auditability: who judged what, against which agreement, on what evidence.
• Retry and remediation that needs to know exactly which conditions or units failed.

What not to use this for

• Ordinary API calls whose success is self-evident to the caller.
• Local-only boolean checks that never leave the system.
• Replacing CI or your evaluator. Keep them; they are the judge.
• Universal authorization or policy enforcement. Spoolis records outcomes; it does not grant authority.
• Generic model benchmarking. An Outcome attests one agreement, not a leaderboard.