@escro/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -61,20 +61,25 @@ interface EscrowAccount {
     state: EscrowState;
     /**
      * SHA-256 hex digest of the canonical UTF-8 JSON serialisation of the {@link TaskSpec}.
-     * Stored on-chain; used by the oracle to verify it is evaluating the correct spec.
+     * Recorded on-chain (the account's `spec_hash` holds this hash, bare, or as `ipfs://<hash>` on
+     * escrows created before P18.T0c), so the buyer and worker (and an arbitrator) can check that a
+     * spec is the one the escrow was created for.
      */
     taskSpecHash: string;
     /**
-     * Content-addressed URI (ipfs:// or ar://) where the full {@link TaskSpec} JSON is pinned.
-     * `null` until the maker uploads the spec via `POST /v1/task-specs`.
+     * The exact string the escrow's on-chain `spec_hash` holds: the bare 64-hex `taskSpecHash`
+     * (escrows created since P18.T0c), `ipfs://<taskSpecHash>` (earlier), `null` before the
+     * spec_uri migration ran. A label for the {@link TaskSpec}'s hash, not a fetchable copy (Escro
+     * stores no spec body; the buyer shares the spec).
      */
     taskSpecUri: string | null;
     /** Base-58 public key of the oracle authority permitted to sign timeout_release / refund_buyer. */
     oracle: string;
     /**
-     * Percentage of `amount` charged as a platform fee, in basis points.
-     * Deducted from the escrow vault on successful settlement.
-     * Valid range: 0–10 000 (0 %–100 %).
+     * Platform fee in basis points. The API serves the value it recorded at registration
+     * (`PLATFORM_FEE_BPS`, the mirror of PlatformConfig `fee_bps`); on chain `create_escrow`
+     * stores PlatformConfig's value. Additive: the buyer deposits `amount` plus the fee and
+     * the worker receives the full `amount`.
      */
     oracleFeeBps: number;
     /** Unix timestamp (seconds) when the escrow PDA was initialised. */
@@ -108,8 +113,8 @@ interface EscrowAccount {
     /** Solana cluster this account belongs to. */
     network: Network;
 }
-/** Protocol-wide aggregate statistics — public, unauthenticated. */
-interface ProtocolStats {
+/** One set of `GET /v1/stats` figures: the public block, or the operator block. */
+interface ProtocolStatsFigures {
     totalEscrows: number;
     totalVolumeUsdc: string;
     /**
@@ -125,6 +130,16 @@ interface ProtocolStats {
     byState: Record<EscrowState, number>;
     activeEscrows: number;
 }
+/** Protocol-wide aggregate statistics: public, unauthenticated. */
+interface ProtocolStats extends ProtocolStatsFigures {
+    /**
+     * Escro-operated fleet figures (ARCHITECTURE section 9): the same fields over
+     * escrows whose buyer and assigned worker are both in the API's operator
+     * allowlist. They are real settlements but not third-party demand, so every
+     * public field excludes them; never sum this block with the public fields.
+     */
+    operator: ProtocolStatsFigures;
+}
 
 /**
  * Broad categories of agent work.
@@ -194,14 +209,16 @@ interface AcceptanceCriterion {
  * This object is:
  *  1. Serialised to canonical UTF-8 JSON (sorted keys, no trailing whitespace).
  *  2. Hashed with SHA-256 → stored on-chain as `EscrowAccount.taskSpecHash`.
- *  3. Pinned to IPFS or Arweave → URI stored as `EscrowAccount.taskSpecUri`.
+ *  3. Written into `create_escrow`'s `spec_hash` bare (since P18.T0c; `ipfs://<hash>` before) and
+ *     recorded as `EscrowAccount.taskSpecUri` (a label for the hash; Escro stores no spec body,
+ *     and the buyer shares the spec itself).
  *
  * Any mutation of the spec changes its hash, invalidating the on-chain record.
  */
 interface TaskSpec {
     /**
      * Semver string identifying the task spec schema version (e.g. `"1.0.0"`).
-     * Allows the oracle and API server to handle format evolution gracefully.
+     * Lets the API, SDKs and bots handle format evolution gracefully.
      * Increment the minor version for backwards-compatible additions;
      * the major version for breaking changes.
      */
@@ -211,13 +228,14 @@ interface TaskSpec {
      */
     taskType: TaskType;
     /**
-     * Complete description of the task, written for both the agent performing it
-     * and the oracle evaluating the result.
+     * Complete description of the task, written for both the worker performing it
+     * and the buyer judging the result (or, in a dispute, the human arbitrator
+     * reading it against the delivery). Escro never evaluates a deliverable.
      *
      * Good descriptions:
      *  - State the goal, not just the method.
      *  - Include any non-obvious constraints (language, style, performance bounds).
-     *  - Are precise enough that an LLM could verify correctness without ambiguity.
+     *  - Are precise enough that the buyer can check the delivery without ambiguity.
      */
     description: string;
     /**
@@ -236,8 +254,9 @@ interface TaskSpec {
 }
 
 /**
- * Exhaustive set of machine-readable error codes returned by the escro.ai REST API
- * in the `code` field of an {@link ApiError} response.
+ * Every machine-readable error code the escro.ai REST API's route handlers send in the `code`
+ * field of an error response (a test derives the set from the API source). A request Fastify
+ * refuses before a handler runs carries Fastify's own `FST_ERR_*` code instead.
  *
  * Consumers should switch on this value to handle errors programmatically
  * rather than parsing the human-readable `error` string.
@@ -247,21 +266,37 @@ type EscrowErrorCode =
 "ESCROW_NOT_FOUND"
 /** The requested operation is not permitted in the escrow's current state. */
  | "ESCROW_INVALID_STATE"
-/** The referenced task spec hash has not been registered. */
- | "TASK_SPEC_NOT_FOUND"
-/** The submitted task spec failed schema validation. */
- | "TASK_SPEC_INVALID"
-/** The caller does not have permission to perform this action. */
+/** Release: the API's RPC still shows the escrow account open at `confirmed`; retry once the release lands. */
+ | "ESCROW_NOT_SETTLED"
+/** Confirm: no transaction for the signature at `confirmed` yet; retry once it lands. */
+ | "TX_NOT_FOUND"
+/** Confirm: the transaction landed with an error. */
+ | "TX_FAILED"
+/** Confirm: the transaction holds no single escrow instruction this route records for the escrow. */
+ | "TX_MISMATCH"
+/** The Solana RPC read failed; retry. */
+ | "RPC_UNAVAILABLE"
+/** Missing, invalid or expired authentication, or a caller not permitted the action. */
  | "UNAUTHORIZED"
-/** The provided transaction signature is invalid or does not match the escrow. */
- | "INVALID_SIGNATURE"
-/** The requested token amount is zero, negative, or exceeds the u64 maximum. */
- | "INVALID_AMOUNT"
-/** The escrow's network does not match the caller's requested network. */
- | "NETWORK_MISMATCH"
+/** EscroBots removal: the signer is not the directory-admin wallet. */
+ | "FORBIDDEN"
+/** EscroBots: the bot descriptor's wallet signature does not verify. */
+ | "INVALID_DESCRIPTOR_SIGNATURE"
+/** EscroBots: the descriptor names a wallet other than the signer. */
+ | "WALLET_MISMATCH"
+/** EscroBots: the wallet was removed from the directory for fraud. */
+ | "WALLET_REMOVED"
+/** EscroBots: the descriptor's timestamp is outside the accepted window. */
+ | "STALE_DESCRIPTOR"
+/** EscroBots: a newer or equal registration already exists for the wallet. */
+ | "DESCRIPTOR_REPLAYED"
+/** EscroBots: no bot is registered for the wallet. */
+ | "BOT_NOT_FOUND"
+/** EscroBots: the requested sort needs a reputation source the deployment lacks. */
+ | "SORT_UNAVAILABLE"
 /** The caller has exceeded the rate limit; retry after the indicated backoff. */
  | "RATE_LIMITED"
-/** An unexpected server-side error occurred; report to escro.ai support. */
+/** An unexpected server-side error occurred. */
  | "INTERNAL_ERROR"
 /** Request body or query parameters failed schema validation. */
  | "VALIDATION_ERROR";
@@ -314,6 +349,35 @@ interface BotDescriptor extends UnsignedBotDescriptor {
     signature: string;
 }
 
+/** The submitted deliverable as the Buyer's review reads it off the escrow read model. */
+interface ReviewDeliverable {
+    /**
+     * SHA-256 hex the worker submitted on-chain (mirrored to the read model). It is the
+     * worker's claim about the artifact: a review re-hashes the real artifact and never
+     * trusts this value on its own.
+     */
+    contentHash: string;
+    /** URI the worker gave for the deliverable or its proof, or null if it gave none. */
+    proofUri: string | null;
+}
+/** A release decision. */
+interface ReviewResult {
+    /** Release payment to the worker. */
+    accept: boolean;
+    /**
+     * When NOT accepting, whether to raise a dispute (human arbitration) rather than hold.
+     * A held SUBMITTED escrow is auto-released to the worker by the 24h protocol timeout,
+     * so a real reject predicate disputes to contest.
+     */
+    dispute: boolean;
+    reason: string;
+}
+/** A named release policy the Buyer's review wires in. */
+interface ReviewPolicy {
+    name: string;
+    evaluate(deliverable: ReviewDeliverable): ReviewResult | Promise<ReviewResult>;
+}
+
 type SolanaCluster = "devnet" | "mainnet";
 
 /** Dispute tally with its outcome split (from the wallet's perspective). */
@@ -405,6 +469,64 @@ interface ServedWalletReputation extends SerializedWalletReputation {
     walletAgeSeconds: number | null;
 }
 
+/**
+ * Base class for all errors thrown by the @escro/sdk. `retryAfterMs` is the
+ * server's Retry-After delay, when it sent one in seconds.
+ */
+declare class EscroError extends Error {
+    readonly code: string;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, code?: string, retryAfterMs?: number | undefined);
+}
+/** The requested escrow was not found (HTTP 404). */
+declare class EscrowNotFoundError extends EscroError {
+    constructor(address: string);
+}
+/**
+ * The reputation endpoint is not available on this deployment (HTTP 404). A 404
+ * from `GET /rep` means no `ReputationSource` is mounted (the surface is
+ * unmounted), NOT that a wallet is unknown - unknown wallets return zeroed raw
+ * components, never a 404. Kept distinct from {@link EscrowNotFoundError}, whose
+ * 404 is about a missing escrow.
+ */
+declare class ReputationUnavailableError extends EscroError {
+    constructor();
+}
+/** The operation is not valid for the escrow's current state (HTTP 409). */
+declare class EscrowStateError extends EscroError {
+    constructor(message: string);
+}
+/** Polling timed out after 24 hours without reaching the expected state. */
+declare class EscrowTimeoutError extends EscroError {
+    constructor(address: string);
+}
+/**
+ * A transaction landed (or was sent) but the API did not record it. `code` is the
+ * server's code (e.g. TX_MISMATCH, TX_FAILED, or TX_NOT_FOUND after the retry
+ * window), `NETWORK_ERROR` when the last attempt never reached the API, or
+ * `HTTP_<status>` when the answer carried no code. Call {@link Escro.confirm} again
+ * with `address` and `signature` to retry, no sooner than `retryAfterMs` when the
+ * API sent one.
+ */
+declare class EscroConfirmError extends EscroError {
+    readonly address: string;
+    readonly signature: string;
+    constructor(address: string, signature: string, code: string, message: string, retryAfterMs?: number);
+}
+/** The caller is not authorized to perform this action (HTTP 401/403). */
+declare class UnauthorizedError extends EscroError {
+    constructor(message?: string);
+}
+/**
+ * A payment rail was requested that is not enabled in this build. The `x402`
+ * (synchronous) rail is reserved (ARCHITECTURE §7a) and lands in Phase 9;
+ * {@link Escro.pay} throws this until then. `rail` names the unavailable rail.
+ */
+declare class EscroRailNotEnabledError extends EscroError {
+    readonly rail: string;
+    constructor(rail: string);
+}
+
 /** Constructor options for the {@link Escro} client. */
 interface EscroOptions {
     /**
@@ -422,7 +544,7 @@ interface EscroOptions {
 }
 /** Parameters for creating a new escrow. */
 interface CreateEscrowParams {
-    /** Full task specification uploaded to IPFS. */
+    /** The full task specification; the API records its hash, never its body. */
     taskSpec: TaskSpec;
     /**
      * Worker's net payment in μUSDC (1 USDC = 1_000_000). Minimum: 5_000_000.
@@ -448,6 +570,21 @@ interface CreateEscrowResult {
     /** Solana transaction signature. */
     signature: string;
 }
+/**
+ * Return value from {@link Escro.releasePaymentWithOutcome}. The release landed on
+ * chain either way; `confirm` says whether the API recorded it. A failed confirm
+ * carries an `EscroConfirmError` (`address`, `signature`, `code`).
+ */
+interface ReleasePaymentOutcome {
+    /** Solana transaction signature of the landed `release_payment`. */
+    signature: string;
+    confirm: {
+        landed: true;
+    } | {
+        landed: false;
+        error: EscroConfirmError;
+    };
+}
 /** Parameters for submitting a deliverable. */
 interface SubmitDeliverableParams {
     /** SHA-256 hex digest (or content-addressed hash) of the deliverable content. */
@@ -457,7 +594,7 @@ interface SubmitDeliverableParams {
 }
 /** Parameters for raising a dispute. */
 interface RaiseDisputeParams {
-    /** Human-readable reason for the dispute (max 200 chars). */
+    /** Human-readable reason for the dispute: non-empty, at most 200 UTF-8 bytes. */
     reason: string;
     /** Optional URL to evidence supporting the dispute. */
     evidence?: string;
@@ -524,7 +661,7 @@ interface WorkerCandidate {
  *
  * PLUMBING ONLY. The escrow rail is the sole implemented backend; the `x402`
  * (synchronous) rail is reserved and lands in Phase 9 as an additive backend.
- * Every name here is a FREEZE CONTRACT that Phase 9 (P9.T5) inherits "by name":
+ * Every name here is a FREEZE CONTRACT that Phase 9 inherits "by name":
  * enabling x402 must not be a breaking change for any kit-generated bot. The
  * shapes below are pinned by a type-level test (src/__tests__/payments.test.ts);
  * Phase 9 may add only OPTIONAL fields.
@@ -591,7 +728,7 @@ declare class Escro {
     constructor(options: EscroOptions);
     /**
      * Create a new escrow: registers with the API, signs and submits the
-     * on-chain `create_escrow` transaction.
+     * on-chain `create_escrow` transaction, then confirms it with the API.
      *
      * @returns `{ escrowId, escrowPda, signature }` — use `escrowPda` for all subsequent calls.
      */
@@ -599,15 +736,27 @@ declare class Escro {
     /**
      * Release payment to the worker. Buyer must be the wallet in the constructor.
      * Builds and submits the `release_payment` on-chain tx FIRST (the chain is the
-     * source of truth), then confirms DB state. The DB confirmation is best-effort:
-     * the oracle sweep reconciles it if it fails.
+     * source of truth), then has the API record it, retrying as
+     * {@link Escro.releasePaymentWithOutcome} does. Use that method to see whether the
+     * API recorded the release.
      *
      * @returns Solana transaction signature.
      */
     releasePayment(address: string): Promise<string>;
+    /**
+     * {@link Escro.releasePayment}, reporting whether the API recorded the release.
+     * `ESCROW_NOT_SETTLED` (the API's RPC does not yet show the escrow closed), the codes
+     * {@link Escro.confirm} retries and a network failure are retried for about 30 s. A
+     * failure never throws: the release already landed, so the signature is returned with
+     * `confirm.landed: false` and an `EscroConfirmError` (the API's code, or
+     * `NETWORK_ERROR` when the last call never reached it).
+     *
+     * @returns `{ signature, confirm }`.
+     */
+    releasePaymentWithOutcome(address: string): Promise<ReleasePaymentOutcome>;
     /**
      * Raise a dispute for an escrow. Either the buyer or the assigned worker
-     * may call this. Signs and submits the `raise_dispute` on-chain tx.
+     * may call this. Signs and submits the `raise_dispute` on-chain tx, then confirms it with the API.
      *
      * @returns Solana transaction signature.
      */
@@ -615,7 +764,7 @@ declare class Escro {
     /**
      * Cancel a funded escrow before any worker has claimed it.
      * Buyer must be the wallet in the constructor. Only valid when state is `FUNDED`.
-     * Signs and submits the `cancel_escrow` on-chain tx; full USDC refund to buyer.
+     * Signs and submits the `cancel_escrow` on-chain tx, then confirms it with the API; full USDC refund to buyer.
      *
      * @returns Solana transaction signature.
      */
@@ -634,14 +783,14 @@ declare class Escro {
     pay(params: PayParams): Promise<PaymentResult>;
     /**
      * Claim an assigned task. Worker must be the wallet in the constructor.
-     * Signs and submits the `claim_task` on-chain tx.
+     * Signs and submits the `claim_task` on-chain tx, then confirms it with the API.
      *
      * @returns Solana transaction signature.
      */
     claimTask(address: string): Promise<string>;
     /**
      * Submit a deliverable for the buyer to review. Worker must be the wallet.
-     * Signs and submits the `submit_deliverable` on-chain tx.
+     * Signs and submits the `submit_deliverable` on-chain tx, then confirms it with the API.
      *
      * @returns Solana transaction signature.
      */
@@ -701,6 +850,20 @@ declare class Escro {
      * @returns protocol-wide {@link ProtocolStats}.
      */
     getStats(): Promise<ProtocolStats>;
+    /**
+     * Ask the API to record the create, claim, submit, cancel or dispute that the
+     * landed `signature` carries; the API verifies it on chain first. Retries a
+     * not-yet-visible transaction, an RPC failure, a gateway error or a rate limit
+     * for about 30 s (waiting at least a sent Retry-After), never a rejection. Throws
+     * {@link EscroConfirmError}; calling again is safe (a replay of a recorded
+     * transition succeeds).
+     */
+    confirm(address: string, signature: string, opts?: {
+        evidence?: string;
+    }): Promise<EscrowAccount>;
+    private retryRecord;
+    private send;
+    private sendAndConfirm;
     /**
      * Fetch an escrow by its PDA address.
      * If `options.poll` is true, polls with exponential backoff until the escrow
@@ -740,6 +903,15 @@ declare class ApiClient {
      * so it surfaces as {@link ReputationUnavailableError}, not EscrowNotFoundError.
      */
     listReputations(): Promise<ServedWalletReputation[]>;
+    /**
+     * GET /rep/:wallet : one wallet's EscroRep RAW components (ARCHITECTURE §9).
+     * Unauthenticated public read (no auth headers). Unknown wallets return zeroed
+     * components, never 404; a 404 means the deployment mounted no reputation
+     * source and surfaces as {@link ReputationUnavailableError}. Shares the public
+     * per-wallet rate budget with every other caller, so fan-outs should use
+     * {@link listReputations} instead.
+     */
+    getReputation(wallet: string): Promise<ServedWalletReputation>;
     /**
      * POST /v1/escrows — create escrow, returns unsigned tx + ids.
      * Requires auth.
@@ -764,8 +936,11 @@ declare class ApiClient {
         unsignedTx: string;
     }>;
     /**
-     * POST /v1/escrows/:address/release — DB-only state update.
-     * Requires auth (buyer). No on-chain tx returned.
+     * POST /v1/escrows/:address/release: records the landed release once the API's RPC shows
+     * the escrow closed. Requires auth (buyer). No on-chain tx returned. A 409
+     * `ESCROW_NOT_SETTLED`, a 5xx or a 429 throws an {@link EscroError} with the server's code,
+     * or `HTTP_<status>` when the answer carries none; {@link Escro.releasePaymentWithOutcome}
+     * decides which to retry. Other refusals throw as every route does.
      */
     releasePaymentDb(address: string): Promise<void>;
     /**
@@ -779,9 +954,17 @@ declare class ApiClient {
      * POST /v1/escrows/:address/dispute — returns unsigned tx.
      * Requires auth (buyer or worker).
      */
-    raiseDispute(address: string, params: RaiseDisputeParams): Promise<{
+    raiseDispute(address: string, params: Pick<RaiseDisputeParams, "reason">): Promise<{
         unsignedTx: string;
     }>;
+    /**
+     * POST /v1/escrows/:address/confirm: the API records the create, claim, submit,
+     * cancel or dispute the landed `signature` carries, after verifying it on chain.
+     * A non-2xx answer throws an {@link EscroError} with the server's code, or
+     * `HTTP_<status>` when the answer carries none; a network failure rejects with
+     * fetch's own error. {@link Escro.confirm} decides which to retry.
+     */
+    confirm(address: string, signature: string, evidence?: string): Promise<EscrowAccount>;
     /**
      * GET /v1/stats — public protocol-wide stats.
      * No auth required. Upstream typing in {@link Escro.getStats} narrows the
@@ -833,47 +1016,6 @@ interface ServiceAdapter {
  */
 declare function serviceResultToSubmitParams(result: ServiceResult): SubmitDeliverableParams;
 
-/** Base class for all errors thrown by the @escro/sdk. */
-declare class EscroError extends Error {
-    readonly code: string;
-    constructor(message: string, code?: string);
-}
-/** The requested escrow was not found (HTTP 404). */
-declare class EscrowNotFoundError extends EscroError {
-    constructor(address: string);
-}
-/**
- * The reputation endpoint is not available on this deployment (HTTP 404). A 404
- * from `GET /rep` means no `ReputationSource` is mounted (the surface is
- * unmounted), NOT that a wallet is unknown - unknown wallets return zeroed raw
- * components, never a 404. Kept distinct from {@link EscrowNotFoundError}, whose
- * 404 is about a missing escrow.
- */
-declare class ReputationUnavailableError extends EscroError {
-    constructor();
-}
-/** The operation is not valid for the escrow's current state (HTTP 409). */
-declare class EscrowStateError extends EscroError {
-    constructor(message: string);
-}
-/** Polling timed out after 24 hours without reaching the expected state. */
-declare class EscrowTimeoutError extends EscroError {
-    constructor(address: string);
-}
-/** The caller is not authorized to perform this action (HTTP 401/403). */
-declare class UnauthorizedError extends EscroError {
-    constructor(message?: string);
-}
-/**
- * A payment rail was requested that is not enabled in this build. The `x402`
- * (synchronous) rail is reserved (ARCHITECTURE §7a) and lands in Phase 9;
- * {@link Escro.pay} throws this until then. `rail` names the unavailable rail.
- */
-declare class EscroRailNotEnabledError extends EscroError {
-    readonly rail: string;
-    constructor(rail: string);
-}
-
 /** Options controlling {@link assertServiceAdapterContract}. */
 interface AdapterContractOptions {
     /**
@@ -966,7 +1108,7 @@ interface GradientsAdapterConfig {
     /** Health-check port. Default: resolves `true`. */
     checkHealth?: () => Promise<boolean>;
 }
-/** Stable id/capabilities, LOCKED against `ADAPTER_DESCRIPTORS.gradients` by a kit test (consult C2). */
+/** Stable id/capabilities, LOCKED against `ADAPTER_DESCRIPTORS.gradients` by a kit test. */
 declare const GRADIENTS_ADAPTER_ID = "bittensor:sn56";
 declare const GRADIENTS_CAPABILITIES: readonly ["fine-tune"];
 /** Stable marker on the demo spec's metadata so the default subnet stub recognizes it. */
@@ -975,7 +1117,7 @@ declare const GRADIENTS_DEMO_MARKER = "gradients-sn56-demo-v1";
 declare const GRADIENTS_DEMO_EVAL_FLOOR = 0.8;
 /**
  * The canned Gradients demo job. Deterministic; its specHash is pinned by a test
- * (consult C8) because the buyer journey depends on hash stability.
+ * because the buyer journey depends on hash stability.
  */
 declare const gradientsDemoJobSpec: TaskSpec;
 /**
@@ -988,7 +1130,7 @@ declare function solveGradientsDemo(): string;
  * The BUYER's independent recompute of the demo eval score in [0, 1]. Reads the
  * substantive output (the predictions) and compares it to the target map the buyer
  * itself defines; it deliberately IGNORES any self-reported `eval.score` in the
- * deliverable, so release can never be worker-controlled (consult C10). Malformed
+ * deliverable, so release can never be worker-controlled. Malformed
  * or unparseable content scores 0 and never throws.
  */
 declare function scoreGradientsDemoDeliverable(content: string | Buffer): number;
@@ -1043,8 +1185,8 @@ declare function solveRidgesDemo(): string;
  * The BUYER's independent recompute of the demo acceptance, as a score in [0, 1].
  * It reads the substantive output (the delivered test outputs) and recomputes the
  * expected FizzBuzz result for each; it deliberately IGNORES any self-reported
- * pass/coverage in the deliverable, so release can never be worker-controlled
- * (consult C10). Semantics:
+ * pass/coverage in the deliverable, so release can never be worker-controlled.
+ * Semantics:
  *   - Any delivered test whose output is wrong = the suite did not pass (exit != 0):
  *     score 0, no matter how much of the battery is covered.
  *   - Otherwise the score is coverage = (distinct battery inputs delivered) / (battery
@@ -1060,7 +1202,7 @@ declare function createRidgesAdapter(config?: RidgesAdapterConfig): ServiceAdapt
 
 /**
  * 404gen (Bittensor SN17) ServiceAdapter: a batch 3D-generation reference adapter,
- * built to the pattern the shipped Gradients (SN56) adapter established (P6.T6a). A
+ * built to the pattern the shipped Gradients (SN56) adapter established. A
  * Worker Bot wraps the 404gen text-to-3D subnet behind the `ServiceAdapter` interface:
  * it swaps a per-task USDC budget into TAO internally, pays subnet miners in TAO to
  * generate a batch of 3D assets, collects the batch deliverable, and returns a
@@ -1105,7 +1247,7 @@ interface Gen404AdapterConfig {
     /** Health-check port. Default: resolves `true`. */
     checkHealth?: () => Promise<boolean>;
 }
-/** Stable id/capabilities, to be locked against `ADAPTER_DESCRIPTORS["404gen"]` by a kit test at merge (consult C2). */
+/** Stable id/capabilities, to be locked against `ADAPTER_DESCRIPTORS["404gen"]` by a kit test at merge. */
 declare const GEN404_ADAPTER_ID = "bittensor:sn17";
 declare const GEN404_CAPABILITIES: readonly ["3d-generation"];
 /** Stable marker on the demo spec's metadata so the default subnet stub recognizes it. */
@@ -1114,7 +1256,7 @@ declare const GEN404_DEMO_MARKER = "404gen-sn17-demo-v1";
 declare const GEN404_DEMO_EVAL_FLOOR = 1;
 /**
  * The canned 404gen demo job. Deterministic; its specHash is pinned by a test
- * (consult C8) because the buyer journey depends on hash stability.
+ * because the buyer journey depends on hash stability.
  */
 declare const gen404DemoJobSpec: TaskSpec;
 /**
@@ -1378,7 +1520,7 @@ declare function solveRenderDemo(): string;
  * the deliverable satisfies all three criteria and 0 otherwise. It checks completion
  * (status), frame presence, and a frame match by RE-RENDERING the scripted scene and
  * comparing the substantive frame; it deliberately IGNORES any self-reported
- * `frameHash`, so release can never be worker-controlled (consult C10). Malformed or
+ * `frameHash`, so release can never be worker-controlled. Malformed or
  * unparseable content scores 0 and never throws.
  */
 declare function scoreRenderDemoDeliverable(content: string | Buffer): number;
@@ -1508,7 +1650,7 @@ declare const gensynDemoJobSpec: TaskSpec;
  */
 declare function createGensynAdapter(config?: GensynAdapterConfig): ServiceAdapter;
 
-/** Stable id/capabilities; locked against the EscroBots registry descriptor by a kit test at merge (consult C2). */
+/** Stable id/capabilities; locked against the EscroBots registry descriptor by a kit test at merge. */
 declare const ZKML_ADAPTER_ID = "zkml";
 declare const ZKML_CAPABILITIES: readonly ["zk-verified-inference"];
 /** Marker on the demo spec's metadata so the default inference port recognizes it. */
@@ -1583,34 +1725,11 @@ declare function verifyZkmlProof(proof: unknown, expected: ZkmlExpectation): Zkm
 /** Decode an inline proof URI (or reject a missing/foreign one) and verify it. */
 declare function verifyZkmlProofUri(uri: string | null | undefined, expected: ZkmlExpectation): ZkmlVerification;
 /** The submitted deliverable as the Buyer's review reads it off the escrow read model. */
-interface ZkmlDeliverable {
-    /**
-     * SHA-256 hex the WORKER submitted on-chain (mirrored to the read model). It is the
-     * worker's CLAIM about the artifact; {@link zkmlProofAutoRelease} re-hashes the real
-     * artifact (via its `fetchContent` port) and never trusts this value on its own.
-     */
-    contentHash: string;
-    /** URI where the ZK proof is (inline `zkml-proof:` or a pinned `ipfs://`), or null. */
-    proofUri: string | null;
-}
+type ZkmlDeliverable = ReviewDeliverable;
 /** A release decision: release, and if not, whether to contest via dispute. */
-interface ZkmlReviewResult {
-    accept: boolean;
-    dispute: boolean;
-    reason: string;
-}
-/**
- * A named release policy the Buyer's review wires in. Field-for-field this mirrors the
- * buyer template's `ReviewPolicy`
- * (packages/create-escro-bot/templates/buyer/src/review.ts). The SDK cannot import the
- * scaffolding templates, and promoting the shared review shapes into `@escro/shared` is
- * a cross-package change owned by `main`, not this lane -- tracked as a merge-time
- * follow-up (LANE-NOTES).
- */
-interface ZkmlReviewPolicy {
-    name: string;
-    evaluate(deliverable: ZkmlDeliverable): Promise<ZkmlReviewResult>;
-}
+type ZkmlReviewResult = ReviewResult;
+/** A named release policy the Buyer's review wires in; `evaluate` may be sync or async. */
+type ZkmlReviewPolicy = ReviewPolicy;
 /** Options for {@link zkmlProofAutoRelease}. */
 interface ZkmlProofAutoReleaseOptions {
     /**
@@ -1697,4 +1816,5 @@ declare function solveZkmlDemo(): string;
  */
 declare function createZkmlAdapter(config?: ZkmlAdapterConfig): ServiceAdapter;
 
-export { AKASH_ADAPTER_ID, AKASH_CAPABILITIES, AKASH_DEMO_ACCEPT_FLOOR, AKASH_DEMO_MARKER, type AcceptanceCriterion, AdapterContractError, type AdapterContractOptions, type AkashAdapterConfig, type Akt, ApiClient, type AutoReleaseDecision, type BotDescriptor, type BotRole, type CreateEscrowParams, type CreateEscrowResult, type DeliverableFormat, type DeliverableType, ENABLED_RAILS, Escro, EscroError, type EscroOptions, EscroRailNotEnabledError, type EscrowAccount, type EscrowErrorCode, EscrowNotFoundError, EscrowPaymentRouter, EscrowState, EscrowStateError, EscrowTimeoutError, GEN404_ADAPTER_ID, GEN404_CAPABILITIES, GEN404_DEMO_EVAL_FLOOR, GEN404_DEMO_MARKER, GENSYN_ADAPTER_ID, GENSYN_CAPABILITIES, GENSYN_DEMO_MARKER, GENSYN_REE_SCHEME, GRADIENTS_ADAPTER_ID, GRADIENTS_CAPABILITIES, GRADIENTS_DEMO_EVAL_FLOOR, GRADIENTS_DEMO_MARKER, type Gen404AdapterConfig, type GensynAdapterConfig, type GensynDeliverableBundle, type GradientsAdapterConfig, LIUM_ADAPTER_ID, LIUM_CAPABILITIES, LIUM_DEMO_ACCEPT_FLOOR, LIUM_DEMO_MARKER, type ListBotsParams, type ListOptions, type LiumAdapterConfig, type Network, type PaginatedResult, type PayParams, type PaymentResult, type PaymentRouter, type PinContent$3 as PinContent, type PollOptions, type ProtocolStats, RAILS, RAILS_DOCS_URL, REFERENCE_MICRO_USDC_PER_AKT, REFERENCE_MICRO_USDC_PER_RENDER, RENDER_ADAPTER_ID, RENDER_CAPABILITIES, RENDER_DEMO_ACCEPT_FLOOR, RENDER_DEMO_MARKER, RIDGES_ADAPTER_ID, RIDGES_CAPABILITIES, RIDGES_DEMO_COVERAGE_TARGET, RIDGES_DEMO_MARKER, type Rail, type RaiseDisputeParams, type ReeExecution, type ReeProof, type ReeVerification, type ReeVerifyContext, type Render, type RenderAdapterConfig, type ReproduceCompute, ReputationUnavailableError, type RidgesAdapterConfig, type RunAkashDeployment, type RunCodingAgent, type RunGpuJob, type RunRenderJob, type ServedWalletReputation, type ServiceAdapter, type ServiceResult, type SubmitDeliverableParams, type SubnetCall, type Tao, type TaskSpec, type TaskType, type TxShape, UnauthorizedError, type UnsignedBotDescriptor, type UsdcToAktSwap, type UsdcToRenderSwap, type UsdcToTaoSwap, type WorkerCandidate, ZKML_ADAPTER_ID, ZKML_CAPABILITIES, ZKML_DEMO_MARKER, ZKML_PROOF_SCHEME, ZKML_PROOF_URI_PREFIX, type ZkmlAdapterConfig, type ZkmlDeliverable, type ZkmlExpectation, type ZkmlInferenceOutput, type ZkmlProof, type ZkmlProofAutoReleaseOptions, type ZkmlReviewPolicy, type ZkmlReviewResult, type ZkmlVerification, akashDemoJobSpec, akt, assertServiceAdapterContract, buildReeProof, buildZkmlProof, computeAkashDemoArtifact, computeLiumDemoArtifact, computeRenderDemoArtifact, create404genAdapter, createAkashAdapter, createGensynAdapter, createGradientsAdapter, createLiumAdapter, createRenderAdapter, createRidgesAdapter, createZkmlAdapter, decodeZkmlProofUri, encodeZkmlProofUri, gen404DemoJobSpec, gensynAutoRelease, gensynDemoJobSpec, gradientsDemoJobSpec, liumDemoJobSpec, renderAmount, renderDemoJobSpec, reproduceGensynCompute, ridgesDemoJobSpec, score404genDemoDeliverable, scoreAkashDemoDeliverable, scoreGradientsDemoDeliverable, scoreLiumDemoDeliverable, scoreRenderDemoDeliverable, scoreRidgesDemoDeliverable, serviceResultToSubmitParams, solveAkashDemo, solveGen404Demo, solveGradientsDemo, solveLiumDemo, solveRenderDemo, solveRidgesDemo, solveZkmlDemo, tao, verifyReeProof, verifyZkmlProof, verifyZkmlProofUri, zkmlDemoJobSpec, zkmlProofAutoRelease };
+export { AKASH_ADAPTER_ID, AKASH_CAPABILITIES, AKASH_DEMO_ACCEPT_FLOOR, AKASH_DEMO_MARKER, AdapterContractError, ApiClient, ENABLED_RAILS, Escro, EscroConfirmError, EscroError, EscroRailNotEnabledError, EscrowNotFoundError, EscrowPaymentRouter, EscrowState, EscrowStateError, EscrowTimeoutError, GEN404_ADAPTER_ID, GEN404_CAPABILITIES, GEN404_DEMO_EVAL_FLOOR, GEN404_DEMO_MARKER, GENSYN_ADAPTER_ID, GENSYN_CAPABILITIES, GENSYN_DEMO_MARKER, GENSYN_REE_SCHEME, GRADIENTS_ADAPTER_ID, GRADIENTS_CAPABILITIES, GRADIENTS_DEMO_EVAL_FLOOR, GRADIENTS_DEMO_MARKER, LIUM_ADAPTER_ID, LIUM_CAPABILITIES, LIUM_DEMO_ACCEPT_FLOOR, LIUM_DEMO_MARKER, RAILS, RAILS_DOCS_URL, REFERENCE_MICRO_USDC_PER_AKT, REFERENCE_MICRO_USDC_PER_RENDER, RENDER_ADAPTER_ID, RENDER_CAPABILITIES, RENDER_DEMO_ACCEPT_FLOOR, RENDER_DEMO_MARKER, RIDGES_ADAPTER_ID, RIDGES_CAPABILITIES, RIDGES_DEMO_COVERAGE_TARGET, RIDGES_DEMO_MARKER, ReputationUnavailableError, UnauthorizedError, ZKML_ADAPTER_ID, ZKML_CAPABILITIES, ZKML_DEMO_MARKER, ZKML_PROOF_SCHEME, ZKML_PROOF_URI_PREFIX, akashDemoJobSpec, akt, assertServiceAdapterContract, buildReeProof, buildZkmlProof, computeAkashDemoArtifact, computeLiumDemoArtifact, computeRenderDemoArtifact, create404genAdapter, createAkashAdapter, createGensynAdapter, createGradientsAdapter, createLiumAdapter, createRenderAdapter, createRidgesAdapter, createZkmlAdapter, decodeZkmlProofUri, encodeZkmlProofUri, gen404DemoJobSpec, gensynAutoRelease, gensynDemoJobSpec, gradientsDemoJobSpec, liumDemoJobSpec, renderAmount, renderDemoJobSpec, reproduceGensynCompute, ridgesDemoJobSpec, score404genDemoDeliverable, scoreAkashDemoDeliverable, scoreGradientsDemoDeliverable, scoreLiumDemoDeliverable, scoreRenderDemoDeliverable, scoreRidgesDemoDeliverable, serviceResultToSubmitParams, solveAkashDemo, solveGen404Demo, solveGradientsDemo, solveLiumDemo, solveRenderDemo, solveRidgesDemo, solveZkmlDemo, tao, verifyReeProof, verifyZkmlProof, verifyZkmlProofUri, zkmlDemoJobSpec, zkmlProofAutoRelease };
+export type { AcceptanceCriterion, AdapterContractOptions, AkashAdapterConfig, Akt, AutoReleaseDecision, BotDescriptor, BotRole, CreateEscrowParams, CreateEscrowResult, DeliverableFormat, DeliverableType, EscroOptions, EscrowAccount, EscrowErrorCode, Gen404AdapterConfig, GensynAdapterConfig, GensynDeliverableBundle, GradientsAdapterConfig, ListBotsParams, ListOptions, LiumAdapterConfig, Network, PaginatedResult, PayParams, PaymentResult, PaymentRouter, PinContent$3 as PinContent, PollOptions, ProtocolStats, Rail, RaiseDisputeParams, ReeExecution, ReeProof, ReeVerification, ReeVerifyContext, ReleasePaymentOutcome, Render, RenderAdapterConfig, ReproduceCompute, RidgesAdapterConfig, RunAkashDeployment, RunCodingAgent, RunGpuJob, RunRenderJob, ServedWalletReputation, ServiceAdapter, ServiceResult, SubmitDeliverableParams, SubnetCall, Tao, TaskSpec, TaskType, TxShape, UnsignedBotDescriptor, UsdcToAktSwap, UsdcToRenderSwap, UsdcToTaoSwap, WorkerCandidate, ZkmlAdapterConfig, ZkmlDeliverable, ZkmlExpectation, ZkmlInferenceOutput, ZkmlProof, ZkmlProofAutoReleaseOptions, ZkmlReviewPolicy, ZkmlReviewResult, ZkmlVerification };