How verification works

Start with the transaction boundary

Spoolis is for transactions where payment depends on whether the agreed outcome actually happened.

For an integration, each check follows the same path:

criterion -> evidence -> verifier -> result -> economic rule

1. Criterion: define the condition before verification.
2. Evidence: supply the artifact or confirmation the criterion requires.
3. Verifier: route the evidence to an available execution method.
4. Result: record what the verifier returned, then apply the agreed rule to determine earned value.

Good verification starts before the work runs. The agreement has to become something software can actually check without changing what was asked. That means writing the acceptance criteria first, declaring required evidence explicitly, and letting downstream systems continue only with accepted work.

Use a pinned outcome recipe

Fetch GET /recipes/qualified-companies-v1, and verify content_sha256 or the ETag if your integration pins the recipe. Pass the response's conditions field unchanged as the conditions input to verify_result or POST /api/v1/verify. Every condition in the qualified-companies recipe is fully evaluable in the keyless sandbox.

The hash proves the recipe is unchanged; it says nothing about the authority or quality of the criteria.

Who runs the check?

Outcome Receipt condition results support four execution methods. Deterministic and human-confirmed checks are live, and AI-assisted execution is live for claim_cited. Schema acceptance of any other method or checker does not mean an executor is live.

If Spoolis cannot support a criterion with an available verification method, it does not invent a verdict.

Result states and what to do next

Every Spool read and verification response reports terminal, settlement_eligible, can_resubmit_evidence, can_rerun, next_step, and decision_authority. Evidence resubmission appends to the existing evidence set and keeps its submitter, provenance, and timestamp.

A failed required condition is a definitive fail even when other checks remain uncertain; a unitized run then earns zero. A unitized partial result is final for that Spool. Accepted units remain settlement-eligible; rejected units need a new delivery. A non-unitized partial, uncertain, or failed active result can accept more evidence and run verification again over the full append-only evidence set.

Method and provenance are separate facts

The method says who or what resolved a condition. Evidence provenance records where an evidence item came from, how it was captured, its artifact reference, when it was observed, and which verifier used it. Provenance is origin and capture metadata, not a trust score. When provenance is missing, the origin is unknown.

Required fields are present
result: pass
method: deterministic
evidence provenance: uploaded JSON

Spoolis does not assign universal assurance labels. A deterministic check over manually entered input and a human confirmation after physical inspection make different claims. The receipt exposes the raw facts so your integration can apply its own policy.

Verifier registry

The live deterministic registry includes checks for structured data, URLs, text, files, hashes, and timestamps. Fixed code and inputs produce a fixed evaluation. Durable evidence can support later reproduction, while a network response is a time-bound observation even when the checking code is fixed. Examples include:

• row_count compares the delivered dataset row count with expected.
• completeness requires every row to carry each of required_fields, non-empty.
• duplicate_rate measures duplicates over key against a maximum rate from 0 to 1.
• url_format requires field to hold a well-formed http or https URL in every row.
• json_path compares a dot or bracket path in a structured evidence payload with expected using operator (eq, gte, lte, contains).
• http_status checks one public HTTP or HTTPS url against expected_status with SSRF protection and a bounded timeout.
• text_contains checks whether delivered text contains an agreed non-empty needle.
• hash_matches computes SHA-256 over delivered file bytes and compares the agreed expected digest.
• deadline_met compares the evidence record timestamp with the agreed ISO due_at, never the evaluation clock.
• claim_cited uses AI-assisted execution to compare a bounded claim with supplied text evidence. It returns verbatim citations that code checks against the supplied evidence.

These are the checker names the API accepts in deterministic_check. Use verification_method: ai_assisted only with claim_cited. Check records and rejection reasons reference the underlying verifier ids in dotted form, for example url.format.

Missing or unreadable input does not pass. Each verifier returns an explicit reason when a check fails.

Verify the receipt, then apply your policy

In the canonical example, Spoolis verifies 100 enrichment records at $1.00 per accepted record, accepts 98, rejects 2 with reasons, and signs a receipt for $98.00 earned. Install the public npm verifier and verify that Outcome Receipt with a pinned trust set.

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

const verification = await verifyOutcomeReceipt(receipt, { trustSet })
if (!verification.valid) throw new Error(verification.reasons.join(', '))

console.log(receipt.amounts.earned)

Offline signature verification proves authenticity without Spoolis uptime. You may optionally call GET /api/v1/receipts/{receipt_id}/status to add correction, revocation, or advisory state before the payment stack acts on the $98.00 earned amount under its own authorization policy.

A valid Ed25519 signature proves the receipt is genuine and unaltered. It does not prove that every underlying check can be reproduced forever, that supplied evidence reflects real-world truth, or that payment was authorized or settled. Deterministic checks over durable evidence can be reproducible. A live URL, external API result, or human confirmation may not be.

Read verify a receipt for package and trust-set details. Read when Spoolis decides and when you decide for the responsibility boundary.

Planner modes are a different vocabulary

The compiler does not propose third-party verification. It becomes runnable only when the agreement explicitly declares an external_judge; the receipt then records external_tool.

Lower-level attestation verification

The signed attestation is the lower-level verdict underneath the Outcome Receipt. Integrations should normally start with the portable receipt. If you need to verify an attestation directly, select the trust set matching its environment, validate its key ID, digests, expiry, amounts, parties, and authority, then verify the canonical payload with Ed25519. A demo attestation has no production settlement authority.

const { signature, signingKeyId, ...payload } = attestation
const bytes = Buffer.from(canonicalSerialize(payload))
const valid = crypto.verify(
  null, bytes, publicKey, Buffer.from(signature, "base64")
)