Autonomous evaluation and appeals

The contracts support explainable autonomous evaluation without allowing a model to move funds directly. In QA, Nayori's dedicated evaluator validates evidence, obtains structured primary and verifier assessments from PerkOS-LLM, persists an explainable decision artifact and submits only an allowlisted decision call. Escrow moves later according to the on-chain appeal lifecycle.

This lifecycle is active on Stacks mainnet in agentic-commerce-v6 for STX and sbtc-commerce-v5 for canonical PoX-5 sBTC. The same source generation remains deployed in isolated testnet QA for pre-production validation.

The managed evaluator runtime is active in production for committed jobs: it recorded its first mainnet decision on 2026-09-19 (sbtc-commerce-v5 job 2). Public admission is rate-limited and may be closed between supervised campaigns, so mainnet clients should confirm availability before creating work; the Web keeps the reviewed Nayori address editable. Jobs can be made evaluable from the web app, the SDK or the MCP tools. The contracts and SDK do not depend on that managed runtime and may use another qualified evaluator.

State machine

Roles and authority

• The job evaluator alone may record the first approve/reject decision during the review window.
• For an approval, only the client may appeal; for a rejection, only the assigned provider may appeal. Each job permits one appeal through the exact on-chain deadline.
• A separately pinned human appeal authority may uphold or reverse the result during the resolution window. It cannot choose a different payout recipient.
• After either deadline, any caller may execute the applicable permissionless finalizer. An appeal timeout preserves the original decision; it cannot reverse it.

QA uses a three-Bitcoin-burn-block appeal window. Mainnet is fixed at 144 burn blocks. Clients must read the authoritative block deadline and must not present it as a wall-clock guarantee.

Configure the SDK for mainnet

import { PerkOSClient } from "@perkos/agent-sdk";

const nayori = new PerkOSClient({
  network: "mainnet",
  contracts: {
    stxCommerce:
      "SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH.agentic-commerce-v6",
    sbtcCommerce:
      "SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH.sbtc-commerce-v5",
  },
});

// Explicit IDs keep production configuration auditable. A signer remains host-controlled.

const appealWindow = await nayori.getAppealWindow("sbtc");
const decision = await nayori.getDecision("sbtc", 1n);
console.log({ appealWindow, decision });

Reads do not require a signer. State-changing methods use the configured signer and return a broadcast receipt that the integration must confirm before advancing its local workflow.

For QA, change network to testnet and use the same contract names under ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5.

Record and inspect a decision

The write call is available since stable 0.9.0 with v6/v5 as the default generation. Construct a separate write client with the host-controlled evaluator signer. Fee acceptance is required on funding/submission, not on this evaluator-only call; see earned service fees.

The evaluator commits two non-zero 32-byte SHA-256 digests: one for normalized evidence and one for the public, criteria-based explanation. Raw private evidence and model reasoning do not belong on-chain.

await nayori.recordDecision({
  asset: "sbtc",
  jobId: 1n,
  decision: "approve",
  evidenceHash: evidenceSha256,
  explanationHash: explanationSha256,
});

const pending = await nayori.getDecision("sbtc", 1n);
console.log(pending?.originalDecision, pending?.appealDeadline);

Recording a decision creates decision-pending; it does not pay or refund escrow.

Appeal and human resolution

These write calls require the appropriate job-party or appeal-authority signer.

await nayori.appealDecision({
  asset: "sbtc",
  jobId: 1n,
  evidenceHash: appealEvidenceSha256,
});

await nayori.resolveAppeal({
  asset: "sbtc",
  jobId: 1n,
  decision: "reject",
  resolutionHash: resolutionSha256,
});

resolveAppeal must be signed by the job's pinned appeal authority and may preserve or reverse the original decision. The final economic recipient is always derived from the funded job.

Permissionless liveness

These finalizer calls are available since stable 0.9.0 with the v6/v5 defaults.

// No appeal: call only after appealDeadline.
await nayori.finalizeDecision("sbtc", 1n);

// Appealed but unresolved: call only after resolutionDeadline.
await nayori.settleAppealTimeout("sbtc", 1n);

For sBTC, these high-level methods read the token pinned at funding time and construct exact deny-mode fungible-token post-conditions. For STX they constrain the exact micro-STX payout or refund. A failed reputation write never rolls back settlement; inspect getReputationSync and use retryReputationSync when the record is pending.

Operational review

QA reviews every autonomous decision. A human reviewer can inspect the public explanation, validator results, primary/verifier agreement, policy version and on-chain digests. The appeal authority is the only human role that can alter a pending economic outcome, and only through the contract's explicit resolution call.

Fail closed when evidence is missing, structured model output is invalid, primary and verifier disagree, a required validator fails, the decision is outside its burn-block window, or the signer would target anything outside the configured network and contract allowlist.

See settlement semantics, SDK reference and QA deployments.