@perkos/agent-sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `@perkos/agent-sdk` are documented here.
 
 ## Unreleased
 
+## 0.7.1 - 2026-09-02
+
+### Changed
+
+- Promote the source-verified `agentic-commerce-v5`, `sbtc-commerce-v4` and
+  `reputation-registry-v3` generation to the default mainnet and testnet deployment map.
+- Make autonomous decisions, role-specific appeals, human resolution and permissionless
+  finalization available without contract overrides.
+
+### Evidence
+
+- Record the exact-source mainnet deployments in blocks `8905872` and `8905874` and configuration
+  through block `8905886` with the fixed 12-block review and 144-block appeal policy.
+- Record controlled mainnet STX and canonical-sBTC appeal canaries passing 47/47 and 50/50 checks,
+  followed by an independent signer-free 75/75 public-state postcheck. These internal actors do
+  not count as external adoption, non-team wallets or revenue.
+
+### Security
+
+- Preserve v4/v3 and earlier generations only as explicit same-network historical overrides.
+- Keep the separately pinned appeal authority outside the SDK signer boundary; the SDK derives
+  settlement recipients from authoritative on-chain state and retains exact deny-mode outflow
+  post-conditions.
+
 ## 0.7.0 - 2026-09-01
 
 ### Added

package/README.md

@@ -9,7 +9,8 @@ This repository is the continuation of `PerkOS-xyz/PerkOS-Agent-SDK`, renamed to
 public SDK with the Nayori product identity. The npm package remains `@perkos/agent-sdk` and the
 complete Git history, releases, issues, and pull requests are preserved.
 
-> Status: 0.7.0 release candidate; 0.6.0 remains the current public npm release. Read clients,
+> Status: 0.7.1 is the release candidate that promotes Nayori's verified v5/v4 contracts as the
+> default integration. Read clients,
 > transaction builders, browser and headless signer
 > adapters, confirmation receipts, safety policies, and a transactional testnet quickstart are
 > implemented. The x402 v2 client and Stacks facilitator foundations are implemented, with
@@ -141,7 +142,7 @@ more than the job requires.
 
 ## Active versioned escrow
 
-Version `0.7.0` selects Nayori's source-verified v4/v3/v3 generation by default on mainnet and
+Version `0.7.1` selects Nayori's source-verified v5/v4/v3 generation by default on mainnet and
 testnet. A normal client therefore needs no contract override:
 
 ```ts
@@ -155,33 +156,35 @@ const perkos = new PerkOSClient({
 const job = await perkos.getJob("sbtc", 7n);
 console.log(job?.submittedAtBurn, job?.reviewDeadline, job?.status);
 
-// After the on-chain Bitcoin review deadline, any signer may trigger the
-// exact provider payout. The plan remains deny-mode with exact escrow outflow.
-await perkos.settleReviewTimeout("sbtc", 7n);
+// The evaluator records an explainable decision without moving escrow.
+await perkos.recordDecision({
+  asset: "sbtc",
+  jobId: 7n,
+  decision: "approve",
+  evidenceHash: evidenceSha256,
+  explanationHash: explanationSha256,
+});
 
 const sync = await perkos.getReputationSync("sbtc", 7n);
 if (sync?.pending) await perkos.retryReputationSync("sbtc", 7n);
 ```
 
-The fixed 12-burn-block review window is readable through `getReviewWindow(asset)`.
-Evaluator completion/rejection is available through the exact deadline; timeout settlement is
-available only after it. Timeout payout is returned as the distinct `timeout-paid` (`u6`) status
-and must not be counted as a completed job or reputation success. A failed reputation write never
-rolls back economic settlement and can be retried permissionlessly.
+The fixed 12-burn-block review window is readable through `getReviewWindow(asset)`. A decision
+opens the appeal period: three burn blocks in isolated QA and 144 on mainnet. The affected client
+or provider may appeal, a separately pinned human authority may resolve, and permissionless
+finalizers preserve liveness after either deadline. A review timeout is returned as the distinct
+`timeout-paid` (`u6`) status and must not be counted as a completed job or reputation success. A
+failed reputation write never rolls back economic settlement and can be retried permissionlessly.
 
-## Autonomous evaluator candidate
+## Autonomous evaluation and appeals
 
-The SDK supports the source-reviewed `agentic-commerce-v5` and `sbtc-commerce-v4` candidate
-through explicit contract overrides. This does not change the active deployment defaults:
+The SDK uses the active source-reviewed `agentic-commerce-v5` and `sbtc-commerce-v4` deployment by
+default:
 
 ```ts
 const autonomous = new PerkOSClient({
-  network: "testnet",
+  network: "mainnet",
   signer,
-  contracts: {
-    stxCommerce: "ST...agentic-commerce-v5",
-    sbtcCommerce: "ST...sbtc-commerce-v4",
-  },
 });
 
 await autonomous.recordDecision({
@@ -213,8 +216,8 @@ pinned when the job was funded. Both the trait argument and exact fungible-token
 that historical token, so rotating the contract's future funding default cannot strand an existing
 escrow.
 
-The previous v3/v2 testnet generation remains supported through explicit overrides and immutable
-at 144 blocks. The active v4/v3/v3 generation first passed on Stacks testnet. Controlled STX and
+The previous v4/v3 and v3/v2 generations remain supported through explicit same-network overrides.
+The historical v4/v3/v3 generation first passed on Stacks testnet. Controlled STX and
 official PoX-5 sBTC complete paths pass 27/27 and 30/30. The real timeout path passes preparation
 20/20, settlement 12/12 and
 separate public-state verification 10/10. Job `u2` settled at burn `11290` in
@@ -223,11 +226,12 @@ ending in `timeout-paid` (`u6`) with zero escrow, one exact 1,000-atomic-unit sB
 completion, reputation or rating credit. The frozen evidence is documented in the
 [contracts/Web repository](https://github.com/PerkOS-xyz/PerkOS-Nayori/blob/main/docs/TESTNET_SECURITY_EVIDENCE.md).
 
-The same exact sources are live on mainnet under
-`SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH`. Deploy/configuration confirmed in blocks
-8885885–8885898. A guarded internal mainnet sBTC job then passed 26/26 checks for exactly 100
-atomic units, ending in `completed` (`u3`) with escrow zero, exact payout, synchronized reputation
-and persisted rating. Those actors are team-operated release evidence, not external adoption,
+The active v5/v4 sources are live on mainnet under
+`SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH`. Deployment confirmed in blocks `8905872` and
+`8905874`, with configuration through `8905886`. Guarded STX and canonical-sBTC appeal canaries
+passed 47/47 and 50/50 checks, followed by an independent 75/75 public-state postcheck. Both jobs
+settled exactly once with zero escrow and synchronized reputation. Those actors are team-operated
+release evidence, not external adoption,
 non-team wallet activity or revenue. The independent external security review remains open.
 
 ## Browser signer (Leather and other Stacks wallets)
@@ -583,22 +587,20 @@ or facilitator-submitted signed transaction.
 - OAuth client secrets and access tokens are application secrets. The SDK returns them to the
   caller but does not persist, log or refresh them automatically.
 
-The independent external security review remains open. Do not treat this release candidate as
-audited software.
+The independent external security review remains open. Do not treat this release as audited
+software.
 
 See [Architecture](docs/ARCHITECTURE.md), [x402 payments](docs/X402_PAYMENTS.md),
 [MPP payments](docs/MPP_PAYMENTS.md), [Partner pilot](docs/PARTNER_PILOT.md) and
 [Security](SECURITY.md) for the trust boundaries and
 responsible disclosure process.
 
-## QA promotion
+## QA-first release
 
-`main` is the canonical integration branch. The `Promote exact main commit to QA` workflow accepts
-only a full commit SHA already contained in `main`, requires a fast-forward from the current `qa`
-branch, reruns verification, package inspection and dependency audit, and then pushes that exact
-SHA without force. The protected branch must grant bypass only to the official GitHub Actions app
-before the first promotion; administrator enforcement must remain enabled. QA consumes an exact
-commit or tarball and never publishes npm as a side effect.
+`qa` is the protected integration branch and `main` is production. Every QA commit must pass the
+SDK verification matrix, package dry-run, dependency audit and a clean-consumer package smoke on
+the Nayori VPS before an exact-SHA release branch may target `main`. npm publication remains a
+separate explicit release action and is never triggered by a branch push.
 
 ## Development
 

package/dist/constants.js

@@ -3,16 +3,16 @@ const TESTNET_DEPLOYER = "ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5";
 export const DEFAULT_DEPLOYMENTS = {
     mainnet: {
         agentRegistry: `${MAINNET_DEPLOYER}.agent-registry`,
-        stxCommerce: `${MAINNET_DEPLOYER}.agentic-commerce-v4`,
-        sbtcCommerce: `${MAINNET_DEPLOYER}.sbtc-commerce-v3`,
+        stxCommerce: `${MAINNET_DEPLOYER}.agentic-commerce-v5`,
+        sbtcCommerce: `${MAINNET_DEPLOYER}.sbtc-commerce-v4`,
         reputationRegistry: `${MAINNET_DEPLOYER}.reputation-registry-v3`,
         sbtcToken: "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token",
         sbtcAssetName: "sbtc-token",
     },
     testnet: {
         agentRegistry: `${TESTNET_DEPLOYER}.agent-registry`,
-        stxCommerce: `${TESTNET_DEPLOYER}.agentic-commerce-v4`,
-        sbtcCommerce: `${TESTNET_DEPLOYER}.sbtc-commerce-v3`,
+        stxCommerce: `${TESTNET_DEPLOYER}.agentic-commerce-v5`,
+        sbtcCommerce: `${TESTNET_DEPLOYER}.sbtc-commerce-v4`,
         reputationRegistry: `${TESTNET_DEPLOYER}.reputation-registry-v3`,
         sbtcToken: "SN3VMHXEN64ZZF71JQ5VESXDWTR301XTTXGF4J8F1.sbtc-token",
         sbtcAssetName: "sbtc-token",

package/docs/ARCHITECTURE.md

@@ -144,19 +144,19 @@ profile.
 Completion, rejection, expiry and versioned review-timeout settlement may transfer funds held by
 the escrow contract rather than by the transaction origin. High-level client methods read the
 current job and escrow balance before building the plan. The resulting post-condition identifies
-the escrow contract principal and the exact amount expected to leave it. For `sbtc-commerce-v2`
-and `sbtc-commerce-v3`, the client also reads the job-pinned token and uses it in both the contract argument and exact
-fungible-token post-condition; a later default-token rotation cannot redirect or strand an
-existing escrow.
-
-The active v4/v3 generation records a fixed 12 Bitcoin burn-block review deadline at submission.
-The immutable earlier v3/v2 testnet generation remains supported at 144 blocks. Through the
-deadline, the evaluator remains the only completion/rejection authority. After it, any principal
-may submit `settle-review-timeout`; the SDK treats the result as `timeout-paid`, not completion.
-Reputation synchronization has its own durable read record and deny-mode retry plan so registry
-unavailability never expands payment authority or rolls back the payout.
-
-Versioned v4/v3/v3 contract IDs are the defaults on both networks. Historical generations remain
+the escrow contract principal and the exact amount expected to leave it. For `sbtc-commerce-v2`,
+`sbtc-commerce-v3` and `sbtc-commerce-v4`, the client also reads the job-pinned token and uses it
+in both the contract argument and exact fungible-token post-condition; a later default-token
+rotation cannot redirect or strand an existing escrow.
+
+The active v5/v4 generation records a fixed 12 Bitcoin burn-block review deadline at submission.
+The evaluator records a hashed decision without moving escrow, after which the affected client or
+provider receives the configured appeal window. A separately pinned human authority resolves an
+appeal; permissionless finalizers preserve liveness after either deadline without choosing a new
+recipient. Reputation synchronization has its own durable read record and deny-mode retry plan so
+registry unavailability never expands payment authority or rolls back settlement.
+
+Versioned v5/v4/v3 contract IDs are the defaults on both networks. Historical generations remain
 available through explicit same-network overrides.
 
 ## Future adapters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perkos/agent-sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "TypeScript SDK for agent identity, escrow settlement, and reputation on Stacks.",
   "type": "module",
   "main": "./dist/index.js",