@dvmkit/sdk 0.0.0 → 0.1.0-rc.1

package/dist/tempo-session-store-FTEEGZXA.js

@@ -0,0 +1,467 @@
+import {
+  parseStoreValue,
+  stringifyStoreValue
+} from "./chunk-YG7G4DPZ.js";
+import {
+  withPostgresTransactionRecovery
+} from "./chunk-H25M54MI.js";
+import {
+  withSdkInitLock
+} from "./chunk-S3XAHZQY.js";
+
+// src/sdk/server/tempo-session-store.ts
+import { AsyncLocalStorage } from "async_hooks";
+var PostgresTempoSessionStore = class {
+  constructor(pool) {
+    this.pool = pool;
+    this.update = this.update.bind(this);
+  }
+  pool;
+  acceptance = new AsyncLocalStorage();
+  /** Create the channel table under the SDK-wide migration lock. */
+  async init() {
+    await withSdkInitLock(this.pool, async () => {
+      await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS mpp_tempo_channels (
+          channel_key TEXT PRIMARY KEY,
+          state_json  TEXT NOT NULL,
+          updated_at  BIGINT NOT NULL
+        )
+      `);
+      await this.pool.query(
+        `CREATE INDEX IF NOT EXISTS idx_mpp_tempo_channels_updated
+           ON mpp_tempo_channels(updated_at)`
+      );
+      await this.pool.query(`
+        CREATE TABLE IF NOT EXISTS mpp_tempo_close_intents (
+          channel_id      TEXT PRIMARY KEY,
+          drain_id        TEXT NOT NULL,
+          reference       TEXT,
+          forecast_pending BOOLEAN NOT NULL DEFAULT FALSE,
+          updated_at      BIGINT NOT NULL
+        )
+      `);
+      await this.pool.query(
+        `ALTER TABLE mpp_tempo_close_intents
+           ADD COLUMN IF NOT EXISTS forecast_pending BOOLEAN NOT NULL DEFAULT FALSE`
+      );
+    });
+  }
+  /** Read one channel snapshot. */
+  async get(key) {
+    const client = this.acceptance.getStore()?.client;
+    const { rows } = await (client ?? this.pool).query(
+      `SELECT state_json FROM mpp_tempo_channels WHERE channel_key = $1`,
+      [key]
+    );
+    return rows[0] ? parseStoreValue(rows[0].state_json) : null;
+  }
+  /** Replace one channel snapshot. Used by mppx only for non-RMW maintenance. */
+  async put(key, value) {
+    await this.update(key, () => ({ op: "set", value, result: void 0 }));
+  }
+  /** Delete one channel snapshot. */
+  async delete(key) {
+    await this.update(key, () => ({ op: "delete", result: void 0 }));
+  }
+  /** Atomic read-modify-write using a row lock shared by every SDK replica. */
+  async update(key, fn) {
+    const acceptance = this.acceptance.getStore();
+    if (acceptance) {
+      const client = await this.acceptanceClient(acceptance);
+      return this.updateInTransaction(client, key, fn, acceptance);
+    }
+    return this.transaction(
+      "tempo_session.update",
+      (client) => this.updateInTransaction(client, key, fn)
+    );
+  }
+  /** Compose voucher acceptance and its ledger mutation under the channel-row lock. */
+  async withVoucherAcceptance(voucher, commit, operation) {
+    const context = {
+      commit,
+      channelId: voucher.channelId.toLowerCase(),
+      cumulativeAmount: voucher.cumulativeAmount
+    };
+    try {
+      const value = await this.acceptance.run(context, operation);
+      await context.client?.query("COMMIT");
+      return { value, result: context.result };
+    } catch (error) {
+      await context.client?.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      const pending = context.pendingClient;
+      context.client = void 0;
+      context.pendingClient = void 0;
+      (await pending?.catch(() => void 0))?.release();
+    }
+  }
+  /**
+   * Check out the acceptance transaction's client, opening it on first demand.
+   *
+   * An operation that never mutates the store therefore never takes a
+   * connection and never opens an empty transaction — the caller sees the same
+   * `result: undefined` it saw before, because nothing committed either way.
+   *
+   * The in-flight checkout is memoized, not just its result: mppx awaits each
+   * store call today, but two concurrent first mutations would otherwise open
+   * two transactions and leak the one nobody keeps a handle to.
+   */
+  acceptanceClient(acceptance) {
+    acceptance.pendingClient ??= (async () => {
+      const client = await this.pool.connect();
+      try {
+        await client.query("BEGIN");
+      } catch (error) {
+        client.release();
+        throw error;
+      }
+      acceptance.client = client;
+      return client;
+    })();
+    return acceptance.pendingClient;
+  }
+  /** Serialize a credit draw with the channel lifecycle that authorizes it. */
+  async withDrawPlacement(channelId, operation, tx) {
+    if (tx) return this.withLockedLifecycle(tx, channelId, operation);
+    return this.transaction(
+      "tempo_session.draw_placement",
+      (client) => this.withLockedLifecycle(client, channelId, operation)
+    );
+  }
+  async withLockedLifecycle(client, channelId, operation) {
+    const key = channelId.toLowerCase();
+    const { rows } = await client.query(
+      `SELECT state_json FROM mpp_tempo_channels WHERE channel_key = $1 FOR UPDATE`,
+      [key]
+    );
+    if (!rows[0]) throw new Error(`Tempo session channel ${key} not found`);
+    const current = parseStoreValue(rows[0].state_json);
+    if (!isRecord(current)) throw new Error(`Tempo session channel ${key} has invalid state`);
+    return operation(client, lifecycleFromState(current));
+  }
+  /**
+   * Compose a terminal ledger resolution with the channel's consumed value.
+   *
+   * Voucher acceptance records spending authority; only a successful job
+   * consumes it. Holding the channel row while the callback locks and settles
+   * the credit keeps that distinction atomic across machines and preserves the
+   * shared channel -> credit lock order.
+   */
+  async withTerminalConsumption(channelId, operation) {
+    const key = channelId.toLowerCase();
+    return this.transaction("tempo_session.terminal_consumption", async (client) => {
+      const { rows } = await client.query(
+        `SELECT state_json FROM mpp_tempo_channels WHERE channel_key = $1 FOR UPDATE`,
+        [key]
+      );
+      if (!rows[0]) throw new Error(`Tempo session channel ${key} not found`);
+      const current = parseStoreValue(rows[0].state_json);
+      if (!isRecord(current)) throw new Error(`Tempo session channel ${key} has invalid state`);
+      const lifecycle = lifecycleFromState(current);
+      const resolved = await operation(client, lifecycle);
+      if (resolved.consume) {
+        if (lifecycle.finalized || lifecycle.closeRequestedAt !== 0n) {
+          throw new Error("Tempo session channel is closing or finalized");
+        }
+        if (resolved.amount < 0n) throw new Error("Tempo session consumption cannot be negative");
+        const spent = lifecycle.spent;
+        const highestVoucherAmount = asBigInt(current.highestVoucherAmount);
+        if (highestVoucherAmount === void 0 || spent + resolved.amount > highestVoucherAmount) {
+          throw new Error(`Tempo session consumption exceeds accepted voucher authority`);
+        }
+        const next = {
+          ...current,
+          spent: spent + resolved.amount,
+          units: Number(current.units ?? 0) + 1
+        };
+        assertMonotonicTransition(current, next);
+        await client.query(
+          `UPDATE mpp_tempo_channels SET state_json = $2, updated_at = $3
+            WHERE channel_key = $1`,
+          [key, stringifyStoreValue(next, "Tempo session state"), Date.now()]
+        );
+      }
+      return resolved.value;
+    });
+  }
+  /** Retire lost backing while holding the channel row ahead of every credit lock. */
+  async withFinalizedCreditLoss(channelId, operation) {
+    const key = channelId.toLowerCase();
+    return this.transaction("tempo_session.finalized_credit_loss", async (client) => {
+      const { rows } = await client.query(
+        `SELECT state_json FROM mpp_tempo_channels WHERE channel_key = $1 FOR UPDATE`,
+        [key]
+      );
+      if (!rows[0]) throw new Error(`Tempo session channel ${key} not found`);
+      const current = parseStoreValue(rows[0].state_json);
+      if (!isRecord(current)) throw new Error(`Tempo session channel ${key} has invalid state`);
+      return operation(client, lifecycleFromState(current));
+    });
+  }
+  /** Page active channel snapshots for the close/settlement watcher. */
+  async listActive(limit = 100, cursor) {
+    const { rows } = await this.pool.query(
+      `SELECT channel_key, state_json, updated_at
+        FROM mpp_tempo_channels
+        WHERE (state_json::jsonb ->> 'finalized') IS DISTINCT FROM 'true'
+          AND ($2::BIGINT IS NULL OR (updated_at, channel_key) > ($2, $3))
+        ORDER BY updated_at, channel_key
+        LIMIT $1`,
+      [limit, cursor?.updatedAt ?? null, cursor?.key ?? null]
+    );
+    return rows.map((row) => ({
+      key: row.channel_key,
+      state: parseStoreValue(row.state_json),
+      updatedAt: Number(row.updated_at)
+    }));
+  }
+  /** Persist a drain's close intent before its credential is broadcast. */
+  async beginClose(channelId, drainId) {
+    return this.runCloseIntentTransaction(channelId, drainId, async (tx, record) => {
+      const { rows } = await tx.query(
+        `SELECT EXISTS (
+           SELECT 1
+             FROM credit_drains d
+             JOIN credits c ON c.credit_id = d.credit_id
+            WHERE c.tempo_channel_id = $1
+              AND d.drain_id = $2
+              AND d.status = 'pending'
+         ) AS pending,
+         (SELECT forecast_pending
+            FROM mpp_tempo_close_intents
+           WHERE channel_id = $1 AND drain_id = $2) AS forecast_pending`,
+        [channelId.toLowerCase(), drainId]
+      );
+      if (!rows[0]?.pending) {
+        throw new Error(`Tempo session drain ${drainId} is no longer pending`);
+      }
+      if (rows[0].forecast_pending !== false) {
+        throw new Error(`Tempo session drain ${drainId} refund forecast is still pending`);
+      }
+      return record;
+    });
+  }
+  /** Reserve a close intent and run its ledger debit in the same transaction. */
+  async withCloseIntent(channelId, drainId, operation) {
+    return this.runCloseIntentTransaction(channelId, drainId, operation);
+  }
+  /**
+   * Resolve a reserved close's forecast under the intent row lock.
+   *
+   * `proceed` opens the broadcast gate. `release` deletes the intent and runs
+   * the ledger restore in the same transaction, but only while the gate is
+   * still pending. A concurrent proceed wins by returning `proceed` to the
+   * releaser, which must not restore value that may already be broadcasting.
+   */
+  async resolveCloseForecast(channelId, drainId, decision, operation) {
+    return this.transaction("tempo_session.resolve_close_forecast", async (client) => {
+      const { rows } = await client.query(
+        `SELECT forecast_pending
+           FROM mpp_tempo_close_intents
+          WHERE channel_id = $1 AND drain_id = $2
+          FOR UPDATE`,
+        [channelId.toLowerCase(), drainId]
+      );
+      if (!rows[0]) {
+        return { outcome: "missing" };
+      }
+      if (!rows[0].forecast_pending) {
+        return { outcome: "proceed" };
+      }
+      if (decision === "proceed") {
+        await client.query(
+          `UPDATE mpp_tempo_close_intents
+              SET forecast_pending = FALSE, updated_at = $3
+            WHERE channel_id = $1 AND drain_id = $2`,
+          [channelId.toLowerCase(), drainId, Date.now()]
+        );
+        return { outcome: "proceed" };
+      }
+      if (!operation) {
+        throw new Error("A Tempo close forecast release requires a ledger operation");
+      }
+      await client.query(
+        `DELETE FROM mpp_tempo_close_intents
+          WHERE channel_id = $1 AND drain_id = $2`,
+        [channelId.toLowerCase(), drainId]
+      );
+      const value = await operation(client);
+      return { outcome: "released", value };
+    });
+  }
+  /** Delete a matching close intent and release its ledger debit atomically. */
+  async releaseCloseIntent(channelId, drainId, operation) {
+    return this.transaction("tempo_session.release_close_intent", async (client) => {
+      await client.query(
+        `DELETE FROM mpp_tempo_close_intents
+          WHERE channel_id = $1 AND drain_id = $2`,
+        [channelId.toLowerCase(), drainId]
+      );
+      return operation(client);
+    });
+  }
+  /** Read a persisted cooperative-close intent or confirmed result. */
+  async getClose(channelId) {
+    const { rows } = await this.pool.query(
+      `SELECT channel_id, drain_id, reference
+         FROM mpp_tempo_close_intents
+        WHERE channel_id = $1`,
+      [channelId.toLowerCase()]
+    );
+    return rows[0] ? closeRecord(rows[0]) : null;
+  }
+  /** Persist proof that a cooperative close reached terminal chain state. */
+  async confirmClose(channelId, drainId, reference) {
+    const { rows } = await this.pool.query(
+      `UPDATE mpp_tempo_close_intents
+          SET reference = COALESCE(reference, $3), updated_at = $4
+        WHERE channel_id = $1 AND drain_id = $2 AND forecast_pending = FALSE
+        RETURNING channel_id, drain_id, reference`,
+      [channelId.toLowerCase(), drainId, reference, Date.now()]
+    );
+    if (!rows[0]) throw new Error(`Tempo session close intent not found`);
+    return closeRecord(rows[0]);
+  }
+  async runCloseIntentTransaction(channelId, drainId, operation) {
+    return this.transaction("tempo_session.close_intent", async (client) => {
+      const record = await this.writeCloseIntent(client, channelId, drainId);
+      return operation(client, record);
+    });
+  }
+  transaction(operation, callback) {
+    return withPostgresTransactionRecovery(this.pool, "dvm-host", operation, callback);
+  }
+  async writeCloseIntent(query, channelId, drainId) {
+    const normalized = channelId.toLowerCase();
+    const { rows } = await query.query(
+      `INSERT INTO mpp_tempo_close_intents
+         (channel_id, drain_id, reference, forecast_pending, updated_at)
+       VALUES ($1, $2, NULL, TRUE, $3)
+       ON CONFLICT (channel_id) DO UPDATE SET updated_at = EXCLUDED.updated_at
+       RETURNING channel_id, drain_id, reference`,
+      [normalized, drainId, Date.now()]
+    );
+    const row = rows[0];
+    if (row.drain_id !== drainId) {
+      throw new Error(`Tempo session channel ${normalized} is already closing for another drain`);
+    }
+    return closeRecord(row);
+  }
+  async updateInTransaction(client, key, fn, acceptance) {
+    await client.query(`SELECT pg_advisory_xact_lock(hashtextextended($1, 1762))`, [key]);
+    const { rows } = await client.query(
+      `SELECT state_json FROM mpp_tempo_channels WHERE channel_key = $1 FOR UPDATE`,
+      [key]
+    );
+    const current = rows[0] ? parseStoreValue(rows[0].state_json) : null;
+    const change = fn(current);
+    if (change.op === "set") {
+      const cumulativeAmount = acceptanceVoucherAmount(acceptance, key, current, change.value);
+      let value = change.value;
+      if (acceptance?.channelId === key.toLowerCase() && isRecord(current)) {
+        value = {
+          ...change.value,
+          spent: asBigInt(current.spent) ?? 0n,
+          units: Number(current.units ?? 0)
+        };
+      }
+      assertMonotonicTransition(current, value);
+      await client.query(
+        `INSERT INTO mpp_tempo_channels (channel_key, state_json, updated_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (channel_key) DO UPDATE
+           SET state_json = EXCLUDED.state_json, updated_at = EXCLUDED.updated_at`,
+        [key, stringifyStoreValue(value, "Tempo session state"), Date.now()]
+      );
+      if (acceptance && cumulativeAmount !== void 0 && acceptance.result === void 0) {
+        const priorCumulativeAmount = isRecord(current) ? asBigInt(current.highestVoucherAmount) ?? 0n : 0n;
+        acceptance.result = await acceptance.commit(client, {
+          key,
+          cumulativeAmount,
+          priorCumulativeAmount,
+          delta: cumulativeAmount - priorCumulativeAmount
+        });
+      }
+    } else if (change.op === "delete") {
+      await client.query(`DELETE FROM mpp_tempo_channels WHERE channel_key = $1`, [key]);
+    }
+    return change.result;
+  }
+};
+function lifecycleFromState(state) {
+  return {
+    finalized: state.finalized === true,
+    closeRequestedAt: asBigInt(state.closeRequestedAt) ?? 0n,
+    spent: asBigInt(state.spent) ?? 0n,
+    settledOnChain: asBigInt(state.settledOnChain) ?? 0n,
+    highestVoucherAmount: asBigInt(state.highestVoucherAmount) ?? 0n
+  };
+}
+function closeRecord(row) {
+  return {
+    channelId: row.channel_id,
+    drainId: row.drain_id,
+    reference: row.reference
+  };
+}
+function assertMonotonicTransition(current, next) {
+  if (!isRecord(next)) throw new Error("Tempo session state must be an object");
+  if (!isRecord(current)) return;
+  for (const field of [
+    "channelId",
+    "chainId",
+    "escrowContract",
+    "payee",
+    "payer",
+    "token",
+    "authorizedSigner",
+    "operator"
+  ]) {
+    if (current[field] !== void 0 && next[field] !== current[field]) {
+      throw new Error(`Tempo session immutable field changed: ${field}`);
+    }
+  }
+  for (const field of ["highestVoucherAmount", "settledOnChain", "spent", "deposit"]) {
+    const before = asBigInt(current[field]);
+    const after = asBigInt(next[field]);
+    const terminalReset = next.finalized === true && after === 0n && field === "deposit";
+    if (before !== void 0 && after !== void 0 && after < before && !terminalReset) {
+      throw new Error(`Tempo session monotonic field decreased: ${field}`);
+    }
+  }
+  const closeRequestedAt = asBigInt(next.closeRequestedAt);
+  if (closeRequestedAt !== void 0 && closeRequestedAt < 0n) {
+    throw new Error("Tempo session closeRequestedAt cannot be negative");
+  }
+  if (current.finalized === true && next.finalized !== true) {
+    throw new Error("Tempo session finalized state cannot be reopened");
+  }
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function asBigInt(value) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  if (typeof value === "string" && /^\d+$/.test(value)) return BigInt(value);
+  return void 0;
+}
+function increasedVoucherAmount(current, next) {
+  if (!isRecord(next)) return void 0;
+  const after = asBigInt(next.highestVoucherAmount);
+  const before = isRecord(current) ? asBigInt(current.highestVoucherAmount) ?? 0n : 0n;
+  return after !== void 0 && after > before ? after : void 0;
+}
+function acceptanceVoucherAmount(acceptance, key, current, next) {
+  if (key.toLowerCase() !== acceptance?.channelId) return void 0;
+  const increased = increasedVoucherAmount(current, next);
+  if (increased !== void 0) return increased;
+  const authorized = isRecord(current) ? asBigInt(current.highestVoucherAmount) : void 0;
+  return authorized !== void 0 && authorized >= acceptance.cumulativeAmount ? acceptance.cumulativeAmount : void 0;
+}
+export {
+  PostgresTempoSessionStore,
+  assertMonotonicTransition
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,135 @@
+import { aX as StreamableJobStore, aY as ReceiptIssuingStore, J as JobRecord, aZ as RequestIdClaim, a_ as RequestIdClaimResult, a9 as JobReceipt, a$ as OutgoingMessage, aa as AppendOutgoingOptions, b0 as PaymentCreditDelta, b1 as VerifyAndCreditResult, b2 as JobCounters, a6 as Message, av as MessageType, K as KVStore, L as Logger, v as ResponseContent, P as PaymentContent, S as SDKJobContext } from '../job-store-C5n6bhap.js';
+import '@cashu/cashu-ts';
+import 'mppx';
+import 'hono';
+import '@x402/core/server';
+import '@x402/evm/batch-settlement/server';
+import 'pg';
+import '@x402/core/types';
+import 'zod';
+
+/**
+ * In-memory JobStore implementing the transactional + streaming surface
+ * (internal-review). Used by unit tests; not production-safe — there's no real
+ * concurrency control beyond JS's single-threaded execution.
+ */
+declare class MemoryJobStore implements StreamableJobStore, ReceiptIssuingStore {
+    private data;
+    private messages;
+    private nextSeq;
+    private messageSubscribers;
+    private notifySubscribers;
+    private reactivationLocks;
+    private requestIdClaims;
+    /** Per-DVM monotonic receipt counter (internal-review) — the `receipt_counter` row. */
+    private receiptCounter;
+    /** Receipt sequence already allocated to a job, keyed by job id. */
+    private receiptSeqs;
+    get(id: string): Promise<JobRecord | undefined>;
+    findJobByPaymentTxHash(txHash: string): Promise<JobRecord | undefined>;
+    findJobByRequestId(requestId: string, requesterPubkey: string): Promise<JobRecord | undefined>;
+    claimRequestId(claim: RequestIdClaim): Promise<RequestIdClaimResult | undefined>;
+    resumeRequestId(claim: RequestIdClaim): Promise<RequestIdClaimResult | undefined>;
+    releaseRequestIdClaim(claim: RequestIdClaim): Promise<void>;
+    save(record: JobRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    claimReceiptSeq(jobId: string): Promise<number>;
+    saveReceipt(jobId: string, receipt: JobReceipt): Promise<JobReceipt | undefined>;
+    appendOutgoing(jobId: string, message: OutgoingMessage, opts?: AppendOutgoingOptions): Promise<number>;
+    recordInbound(jobId: string, message: OutgoingMessage): Promise<number>;
+    verifyAndCredit(jobId: string, seq: number, credit: PaymentCreditDelta | null): Promise<VerifyAndCreditResult>;
+    getVerifiedInbound(jobId: string, seq: number): Promise<VerifyAndCreditResult | undefined>;
+    markInboundFailed(jobId: string, seq: number, _reason: string): Promise<void>;
+    findStaleJobs(processingThresholdMs: number, awaitingThresholdMs: number, limit: number, capabilities: string[] | null): Promise<JobRecord[]>;
+    heartbeatActiveJobs(jobIds: string[], now: number): Promise<void>;
+    cancelStaleJob(jobId: string, expectedActivityBefore: number, reason: string, terminalStatus: "failed" | "cancelled"): Promise<boolean>;
+    cancelJob(jobId: string, reason: string): Promise<boolean>;
+    getCounters(jobId: string): Promise<JobCounters | undefined>;
+    claimForProcessing(jobId: string): Promise<boolean>;
+    tryReactivationLock<T>(jobId: string, fn: () => Promise<T>): Promise<{
+        acquired: true;
+        result: T;
+    } | {
+        acquired: false;
+    }>;
+    subscribeMessages(jobId: string, afterSeq: number, onMessage: (msg: Message) => void): Promise<() => void>;
+    subscribeNotifications(jobId: string, onNotify: () => void): Promise<() => void>;
+    getMessages(jobId: string, afterSeq: number): Promise<Message[]>;
+    initStreaming(): Promise<void>;
+    shutdownStreaming(): Promise<void>;
+    /**
+     * Shared body of `cancelStaleJob` (activity cutoff supplied) and `cancelJob`
+     * (`null` cutoff — unconditional). Mirrors `PostgresJobStore.terminateJob`:
+     * the terminal status and the final `cancel` message land together and the
+     * notify fires before the incremental log is cleaned up.
+     */
+    private terminateJob;
+    private allocateSeq;
+    private messagesFor;
+    private notify;
+    private fireNotifyOnly;
+}
+
+/** Recorded outbound message. */
+interface RecordedMessage {
+    /** Message type (e.g. "text", "artifact", "prompt", "complete"). */
+    type: MessageType;
+    /** Message content payload. */
+    content: Record<string, unknown>;
+}
+/** Options for creating a test context. */
+interface TestContextOpts<State = Record<string, unknown>, Input = string> {
+    /** Override the job ID. Default: "test-job-1". */
+    jobId?: string;
+    /** Freeform tags describing the job type. Default: []. */
+    tags?: string[];
+    /** Job input — string for unstructured, or the parsed type for schema-based DVMs. */
+    input?: Input;
+    /** Job parameters as key-value pairs. */
+    params?: Record<string, string>;
+    /** Opaque requester identifier. */
+    requesterId?: string;
+    /** Total msats paid so far. */
+    paidMsats?: number;
+    /** Initial per-job state (cloned to avoid test pollution). */
+    state?: State;
+    /** Environment variables available via ctx.env. */
+    env?: Record<string, string>;
+    /** KV store instance. Default: in-memory MemoryKVStore. */
+    store?: KVStore;
+    /** Logger instance. Default: no-op logger. */
+    log?: Logger;
+    /** Pre-programmed responses for prompt() calls, keyed by prompt ID. */
+    responses?: Record<string, ResponseContent>;
+    /** Pre-programmed payment for requestPayment() calls. */
+    payment?: PaymentContent;
+}
+/** Extended SDKJobContext exposing test inspection properties. */
+interface TestJobContext<State = Record<string, unknown>, Input = string> extends SDKJobContext<State, Input> {
+    /** All outbound messages sent during the handler. */
+    readonly messages: RecordedMessage[];
+    /** Whether complete() was called. */
+    readonly completed: boolean;
+    /** Whether fail() was called. */
+    readonly failed: boolean;
+    /** Whether fail() was called with `{ refund: true }`. */
+    readonly refundRequested: boolean;
+    /** The summary string passed to complete(). */
+    readonly summary: string | undefined;
+    /** The error string passed to fail(). */
+    readonly failError: string | undefined;
+    /**
+     * Cancel the job under test (internal-review) — aborts `ctx.signal` exactly as a
+     * caller cancel, idle timeout, or stale-sweep would in the real runtime, and
+     * puts the context into the same post-terminal shape: every emitter
+     * (`text` / `artifact` / `sendMessage` / `working` / `progress` /
+     * `complete` / `fail`) becomes a no-op, and `prompt` / `requestPayment`
+     * reject with `JobCancelledError` rather than hanging. Use it to assert your
+     * handler stops work after cancellation.
+     */
+    cancel(reason?: string): void;
+}
+/** Create a test-only SDKJobContext for unit testing DVM handlers. */
+declare function createTestContext<State = Record<string, unknown>, Input = string>(opts?: TestContextOpts<State, Input>): TestJobContext<State, Input>;
+
+export { MemoryJobStore, type RecordedMessage, type TestContextOpts, type TestJobContext, createTestContext };