@pinionengineering/prover-client 0.9.0 → 0.11.0

package/dist/client.d.ts

@@ -8,7 +8,7 @@
  * Pass the full base URL including the path prefix, e.g.:
  *   new PinionProverClient("https://hydrogen.pinion.build/prover", { getToken })
  */
-import type { AuditResult, ChallengeKeyInfo, CreateKeyResult, ParsedSetup, ProveJobStatusResponse, RawSetupResponse, TagJobListEntry, TagJobProgress, TagJobStatusResponse, TagResponse } from './types.js';
+import type { AuditResult, ChallengeKeyInfo, CreateKeyResult, ParsedSetup, ProveJobStatusResponse, ProveSubmission, RawSetupResponse, TagJobListEntry, TagJobProgress, TagJobStatusResponse, TagResponse, TagSubmission } from './types.js';
 export interface PinionProverClientOptions {
     /**
      * Returns a JWT Bearer token for authenticated endpoints, or null/undefined
@@ -20,7 +20,7 @@ export interface PinionProverClientOptions {
  * Options for the audit() convenience wrapper.
  *
  * For exact control over block count, use buildChallenge(n, total) +
- * prove() + verifyProof() directly.
+ * prove() + waitForProve() + verifyProof() directly.
  */
 export interface AuditOptions {
     /**
@@ -36,13 +36,31 @@ export interface AuditOptions {
      * For an exact block count use buildChallenge(n, total) + prove() + verifyProof().
      */
     challengePct?: number;
+    /** Milliseconds between GET /prove/:job_id polls during audit()'s wait
+     * phase. Default 500. */
+    pollIntervalMs?: number;
+    /**
+     * Optional cancellation of audit()'s wait phase. There is no default
+     * deadline — omit to wait as long as the proof takes. Pass
+     * `AbortSignal.timeout(ms)` to restore a fixed ceiling.
+     */
+    signal?: AbortSignal;
+    /** Called after every status poll with the raw status string
+     * ("prove-queued" | "prove-running") — for progress UI. There is no
+     * per-block progress signal for proving, unlike tag()'s onProgress. */
+    onStatus?: (status: string) => void;
 }
-/** Options for tag()'s internal job-status polling. */
-export interface TagOptions {
+/** Options for waitForTag()'s job-status polling. */
+export interface WaitForTagOptions {
     /** Milliseconds between GET /tag/:job_id polls. Default 1000. */
     pollIntervalMs?: number;
-    /** Give up and throw TagTimeoutError after this long. Default 10 minutes. */
-    timeoutMs?: number;
+    /**
+     * Optional cancellation. There is no default deadline — omit to wait
+     * indefinitely. Pass `AbortSignal.timeout(ms)` to restore the old fixed
+     * ceiling (waitForTag() throws TagTimeoutError when the signal fires
+     * before the job reaches a terminal state).
+     */
+    signal?: AbortSignal;
     /**
      * Called after every status poll with the latest progress and the raw
      * status string ("tag-queued" | "tag-planning" | "tag-running" |
@@ -54,17 +72,28 @@ export interface TagOptions {
      */
     onProgress?: (progress: TagJobProgress, status: string) => void;
 }
-/** Options for prove()'s internal job-status polling. */
-export interface ProveOptions {
+/** Options for waitForProve()'s job-status polling. */
+export interface WaitForProveOptions {
     /** Milliseconds between GET /prove/:job_id polls. Default 500. */
     pollIntervalMs?: number;
     /**
-     * Give up and throw ProveTimeoutError after this long. Default 60
-     * seconds — much shorter than tag()'s default, since a proof round is one
-     * bounded crypto operation over the sampled blocks, not a per-block loop
-     * over an entire file.
+     * Optional cancellation. There is no default deadline — omit to wait
+     * indefinitely. Pass `AbortSignal.timeout(ms)` to restore the old fixed
+     * ceiling (waitForProve() throws ProveTimeoutError when the signal fires
+     * before the job reaches a terminal state).
      */
-    timeoutMs?: number;
+    signal?: AbortSignal;
+    /**
+     * The challenge/roots this job was submitted with. Optional, but passing
+     * them lets a thrown ProveFailedError/ProveTimeoutError carry enough to
+     * reconstruct a retry — pass what prove() gave you back.
+     */
+    challenge?: string;
+    roots?: string[];
+    /** Called after every status poll with the raw status string
+     * ("prove-queued" | "prove-running"). There is no per-block progress
+     * signal for proving, unlike waitForTag()'s onProgress. */
+    onStatus?: (status: string) => void;
 }
 export declare class PinionProverClient {
     private readonly baseUrl;
@@ -98,20 +127,27 @@ export declare class PinionProverClient {
      * authentication tags, and store them under keyId.
      *
      * The root must already be in the "pinned" lifecycle state for the
-     * authenticated account.  Tagging runs asynchronously on the server —
-     * this enqueues the job and polls GET /api/v1/tag/:job_id until it
-     * reaches a terminal state, so the returned promise resolves only once
-     * tagging is actually done (matching the pre-async blocking behavior).
-     * Call getSetup() after tagging to get the updated block ID lists for the
-     * next audit cycle.
-     *
-     * Throws TagFailedError if the job reaches "tag-failed", or
-     * TagTimeoutError if it doesn't reach a terminal state within
-     * options.timeoutMs.
+     * authenticated account. Tagging runs asynchronously on the server — this
+     * submits the job and returns immediately with a job handle. Poll
+     * tagStatus(jobId) yourself, or await waitForTag(jobId, options) to wait
+     * for a terminal state (with no default deadline — pass `signal:
+     * AbortSignal.timeout(ms)` if you want one). Call getSetup() after
+     * tagging completes to get the updated block ID lists for the next audit
+     * cycle.
      */
-    tag(root: string, keyId: string, options?: TagOptions): Promise<TagResponse>;
-    /** Poll the status of a tag job started by tag(). Exposed for callers that want progress UI without waiting on tag()'s full promise. */
+    tag(root: string, keyId: string): Promise<TagSubmission>;
+    /** Poll the status of a tag job started by tag(). Exposed for callers that want progress UI without waiting on waitForTag()'s full promise. */
     tagStatus(jobId: string): Promise<TagJobStatusResponse>;
+    /**
+     * Wait for a tag job started by tag() to reach a terminal state, polling
+     * tagStatus(jobId) on an interval.
+     *
+     * There is no default deadline — this waits as long as the job takes
+     * unless options.signal is given and fires first, in which case it
+     * throws TagTimeoutError with the last-seen status. Throws TagFailedError
+     * if the job reaches "tag-failed".
+     */
+    waitForTag(jobId: string, options?: WaitForTagOptions): Promise<TagResponse>;
     /**
      * List the caller's tag jobs, most recently created first.
      *
@@ -129,34 +165,42 @@ export declare class PinionProverClient {
     /**
      * POST /prove — unauthenticated, the server resolves the account from key_id.
      *
-     * Proving is asynchronous: this posts the challenge, then polls GET
-     * /prove/:job_id until the job reaches a terminal state, so the returned
-     * promise resolves only once a proof is actually ready (matching the
-     * pre-async blocking behavior). Returns the raw proof bytes. Most callers
-     * should use audit() instead, which also cryptographically verifies the
-     * response.
+     * Proving is asynchronous: this submits the challenge and returns
+     * immediately with a job handle. Poll proveStatus(jobId) yourself, or
+     * await waitForProve(jobId, options) to wait for a terminal state (with
+     * no default deadline — pass `signal: AbortSignal.timeout(ms)` if you
+     * want one). Most callers should use audit() instead, which submits,
+     * waits, and cryptographically verifies the response in one call.
      *
      * @param keyId       Challenge key ID.
      * @param roots       CID strings to prove, in the same order as the challenge.
      * @param challenge   base64(JSON(WireChallenge)) from buildChallenge().
      * @param challengeId Optional idempotency key. If a caller's own retry
      *                    logic re-calls prove() for what is logically the
-     *                    same request (e.g. after a timeout with an unclear
-     *                    outcome), passing the same challengeId across those
-     *                    attempts makes the server return the original job
-     *                    instead of starting a redundant one. Leave unset for
-     *                    normal audit rounds — each is a fresh, independently
-     *                    random challenge, which should never be deduped
-     *                    against a previous one.
+     *                    same request (e.g. after giving up waiting on an
+     *                    earlier attempt with an unclear outcome), passing the
+     *                    same challengeId across those attempts makes the
+     *                    server return the original job instead of starting a
+     *                    redundant one. Leave unset for normal audit rounds —
+     *                    each is a fresh, independently random challenge,
+     *                    which should never be deduped against a previous one.
      *
      * Throws PinNotActiveError (409, checked synchronously before any job is
-     * created), ProveFailedError if the job reaches "prove-failed", or
-     * ProveTimeoutError if it doesn't reach a terminal state within
-     * options.timeoutMs.
+     * created) or ProverError for any other non-2xx submit response.
      */
-    prove(keyId: string, roots: string[], challenge: string, challengeId?: string, options?: ProveOptions): Promise<Uint8Array>;
-    /** Poll the status of a proof job started by prove(). Exposed for callers that want to observe progress without waiting on prove()'s full promise. */
+    prove(keyId: string, roots: string[], challenge: string, challengeId?: string): Promise<ProveSubmission>;
+    /** Poll the status of a proof job started by prove(). Exposed for callers that want to observe progress without waiting on waitForProve()'s full promise. */
     proveStatus(jobId: string): Promise<ProveJobStatusResponse>;
+    /**
+     * Wait for a proof job started by prove() to reach a terminal state,
+     * polling proveStatus(jobId) on an interval. Returns the raw proof bytes.
+     *
+     * There is no default deadline — this waits as long as the proof takes
+     * unless options.signal is given and fires first, in which case it
+     * throws ProveTimeoutError with the last-seen status. Throws
+     * ProveFailedError if the job reaches "prove-failed".
+     */
+    waitForProve(jobId: string, options?: WaitForProveOptions): Promise<Uint8Array>;
     /**
      * Run one audit round against a pre-fetched setup.
      *
@@ -176,6 +220,10 @@ export declare class PinionProverClient {
      * const result = await client.audit(keyId, setup, { challengePct: 100 });
      * ```
      *
+     * Waits for the proof with no default deadline — pass `options.signal` if
+     * you want to cancel or bound how long this waits (e.g.
+     * `AbortSignal.timeout(60_000)` for the old fixed ceiling).
+     *
      * Throws `PinNotActiveError` if any challenged root is no longer pinned.
      */
     audit(keyId: string, setup: ParsedSetup, options?: AuditOptions): Promise<AuditResult>;
@@ -214,29 +262,49 @@ export declare class PinNotActiveError extends Error {
     readonly cid: string;
     constructor(cid: string);
 }
-/** Thrown by tag() when the async tag job reaches the "tag-failed" state. */
+/** Thrown by waitForTag() when the async tag job reaches the "tag-failed" state. */
 export declare class TagFailedError extends Error {
     readonly jobId: string;
     readonly reason: string;
     constructor(jobId: string, reason: string);
 }
-/** Thrown by tag() when the job hasn't reached a terminal state within the configured timeout. */
+/**
+ * Thrown by waitForTag() when its `options.signal` fires before the job
+ * reaches a terminal state. There is no default deadline anymore — this
+ * only happens if the caller opted into one (e.g. `signal:
+ * AbortSignal.timeout(ms)`).
+ */
 export declare class TagTimeoutError extends Error {
     readonly jobId: string;
     readonly lastStatus: string;
     constructor(jobId: string, lastStatus: string);
 }
-/** Thrown by prove() when the async proof job reaches the "prove-failed" state. */
+/** Thrown by waitForProve() when the async proof job reaches the "prove-failed" state. */
 export declare class ProveFailedError extends Error {
     readonly jobId: string;
     readonly reason: string;
-    constructor(jobId: string, reason: string);
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    readonly challenge: string | undefined;
+    readonly roots: string[] | undefined;
+    constructor(jobId: string, reason: string, 
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    challenge: string | undefined, roots: string[] | undefined);
 }
-/** Thrown by prove() when the job hasn't reached a terminal state within the configured timeout. */
+/**
+ * Thrown by waitForProve() when its `options.signal` fires before the job
+ * reaches a terminal state. There is no default deadline anymore — this
+ * only happens if the caller opted into one (e.g. `signal:
+ * AbortSignal.timeout(ms)`).
+ */
 export declare class ProveTimeoutError extends Error {
     readonly jobId: string;
     readonly lastStatus: string;
-    constructor(jobId: string, lastStatus: string);
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    readonly challenge: string | undefined;
+    readonly roots: string[] | undefined;
+    constructor(jobId: string, lastStatus: string, 
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    challenge: string | undefined, roots: string[] | undefined);
 }
 /**
  * Decode a raw /setup response into a ParsedSetup.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -71,45 +71,57 @@ export class PinionProverClient {
      * authentication tags, and store them under keyId.
      *
      * The root must already be in the "pinned" lifecycle state for the
-     * authenticated account.  Tagging runs asynchronously on the server —
-     * this enqueues the job and polls GET /api/v1/tag/:job_id until it
-     * reaches a terminal state, so the returned promise resolves only once
-     * tagging is actually done (matching the pre-async blocking behavior).
-     * Call getSetup() after tagging to get the updated block ID lists for the
-     * next audit cycle.
-     *
-     * Throws TagFailedError if the job reaches "tag-failed", or
-     * TagTimeoutError if it doesn't reach a terminal state within
-     * options.timeoutMs.
+     * authenticated account. Tagging runs asynchronously on the server — this
+     * submits the job and returns immediately with a job handle. Poll
+     * tagStatus(jobId) yourself, or await waitForTag(jobId, options) to wait
+     * for a terminal state (with no default deadline — pass `signal:
+     * AbortSignal.timeout(ms)` if you want one). Call getSetup() after
+     * tagging completes to get the updated block ID lists for the next audit
+     * cycle.
      */
-    async tag(root, keyId, options = {}) {
-        const pollIntervalMs = options.pollIntervalMs ?? 1000;
-        const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+    async tag(root, keyId) {
         const { job_id: jobId } = await this.post('/api/v1/tag', {
             root,
             key_id: keyId,
         });
-        const deadline = Date.now() + timeoutMs;
-        for (;;) {
-            const status = await this.tagStatus(jobId);
-            if (status.progress)
-                options.onProgress?.(status.progress, status.status);
-            if (status.status === 'tag-done') {
-                return { block_ids: status.block_ids, block_count: status.block_count };
-            }
-            if (status.status === 'tag-failed') {
-                throw new TagFailedError(jobId, status.error ?? 'unknown error');
-            }
-            if (Date.now() >= deadline) {
-                throw new TagTimeoutError(jobId, status.status);
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-        }
+        return { jobId, root, keyId };
     }
-    /** Poll the status of a tag job started by tag(). Exposed for callers that want progress UI without waiting on tag()'s full promise. */
+    /** Poll the status of a tag job started by tag(). Exposed for callers that want progress UI without waiting on waitForTag()'s full promise. */
     async tagStatus(jobId) {
         return this.get(`/api/v1/tag/${encodeURIComponent(jobId)}`);
     }
+    /**
+     * Wait for a tag job started by tag() to reach a terminal state, polling
+     * tagStatus(jobId) on an interval.
+     *
+     * There is no default deadline — this waits as long as the job takes
+     * unless options.signal is given and fires first, in which case it
+     * throws TagTimeoutError with the last-seen status. Throws TagFailedError
+     * if the job reaches "tag-failed".
+     */
+    async waitForTag(jobId, options = {}) {
+        const pollIntervalMs = options.pollIntervalMs ?? 1000;
+        const status = await pollUntilTerminal({
+            fetchStatus: () => this.tagStatus(jobId),
+            isTerminal: (s) => s.status === 'tag-done' || s.status === 'tag-failed',
+            pollIntervalMs,
+            signal: options.signal,
+            onTick: (s) => {
+                if (s.progress)
+                    options.onProgress?.(s.progress, s.status);
+            },
+        }).catch((e) => {
+            if (e instanceof PollAbortedError) {
+                const last = e.lastStatus;
+                throw new TagTimeoutError(jobId, last?.status ?? 'unknown');
+            }
+            throw e;
+        });
+        if (status.status === 'tag-failed') {
+            throw new TagFailedError(jobId, status.error ?? 'unknown error');
+        }
+        return { block_ids: status.block_ids, block_count: status.block_count };
+    }
     /**
      * List the caller's tag jobs, most recently created first.
      *
@@ -134,34 +146,30 @@ export class PinionProverClient {
     /**
      * POST /prove — unauthenticated, the server resolves the account from key_id.
      *
-     * Proving is asynchronous: this posts the challenge, then polls GET
-     * /prove/:job_id until the job reaches a terminal state, so the returned
-     * promise resolves only once a proof is actually ready (matching the
-     * pre-async blocking behavior). Returns the raw proof bytes. Most callers
-     * should use audit() instead, which also cryptographically verifies the
-     * response.
+     * Proving is asynchronous: this submits the challenge and returns
+     * immediately with a job handle. Poll proveStatus(jobId) yourself, or
+     * await waitForProve(jobId, options) to wait for a terminal state (with
+     * no default deadline — pass `signal: AbortSignal.timeout(ms)` if you
+     * want one). Most callers should use audit() instead, which submits,
+     * waits, and cryptographically verifies the response in one call.
      *
      * @param keyId       Challenge key ID.
      * @param roots       CID strings to prove, in the same order as the challenge.
      * @param challenge   base64(JSON(WireChallenge)) from buildChallenge().
      * @param challengeId Optional idempotency key. If a caller's own retry
      *                    logic re-calls prove() for what is logically the
-     *                    same request (e.g. after a timeout with an unclear
-     *                    outcome), passing the same challengeId across those
-     *                    attempts makes the server return the original job
-     *                    instead of starting a redundant one. Leave unset for
-     *                    normal audit rounds — each is a fresh, independently
-     *                    random challenge, which should never be deduped
-     *                    against a previous one.
+     *                    same request (e.g. after giving up waiting on an
+     *                    earlier attempt with an unclear outcome), passing the
+     *                    same challengeId across those attempts makes the
+     *                    server return the original job instead of starting a
+     *                    redundant one. Leave unset for normal audit rounds —
+     *                    each is a fresh, independently random challenge,
+     *                    which should never be deduped against a previous one.
      *
      * Throws PinNotActiveError (409, checked synchronously before any job is
-     * created), ProveFailedError if the job reaches "prove-failed", or
-     * ProveTimeoutError if it doesn't reach a terminal state within
-     * options.timeoutMs.
+     * created) or ProverError for any other non-2xx submit response.
      */
-    async prove(keyId, roots, challenge, challengeId, options = {}) {
-        const pollIntervalMs = options.pollIntervalMs ?? 500;
-        const timeoutMs = options.timeoutMs ?? 60 * 1000;
+    async prove(keyId, roots, challenge, challengeId) {
         const resp = await fetch(`${this.baseUrl}/prove`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -175,25 +183,41 @@ export class PinionProverClient {
             throw new ProverError(resp.status, await resp.text().catch(() => ''));
         }
         const { job_id: jobId } = await parseJsonBody(resp);
-        const deadline = Date.now() + timeoutMs;
-        for (;;) {
-            const status = await this.proveStatus(jobId);
-            if (status.status === 'prove-done') {
-                return base64ToBytes(status.proof ?? '');
-            }
-            if (status.status === 'prove-failed') {
-                throw new ProveFailedError(jobId, status.error ?? 'unknown error');
-            }
-            if (Date.now() >= deadline) {
-                throw new ProveTimeoutError(jobId, status.status);
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-        }
+        return { jobId, challenge, roots };
     }
-    /** Poll the status of a proof job started by prove(). Exposed for callers that want to observe progress without waiting on prove()'s full promise. */
+    /** Poll the status of a proof job started by prove(). Exposed for callers that want to observe progress without waiting on waitForProve()'s full promise. */
     async proveStatus(jobId) {
         return this.get(`/prove/${encodeURIComponent(jobId)}`);
     }
+    /**
+     * Wait for a proof job started by prove() to reach a terminal state,
+     * polling proveStatus(jobId) on an interval. Returns the raw proof bytes.
+     *
+     * There is no default deadline — this waits as long as the proof takes
+     * unless options.signal is given and fires first, in which case it
+     * throws ProveTimeoutError with the last-seen status. Throws
+     * ProveFailedError if the job reaches "prove-failed".
+     */
+    async waitForProve(jobId, options = {}) {
+        const pollIntervalMs = options.pollIntervalMs ?? 500;
+        const status = await pollUntilTerminal({
+            fetchStatus: () => this.proveStatus(jobId),
+            isTerminal: (s) => s.status === 'prove-done' || s.status === 'prove-failed',
+            pollIntervalMs,
+            signal: options.signal,
+            onTick: (s) => options.onStatus?.(s.status),
+        }).catch((e) => {
+            if (e instanceof PollAbortedError) {
+                const last = e.lastStatus;
+                throw new ProveTimeoutError(jobId, last?.status ?? 'unknown', options.challenge, options.roots);
+            }
+            throw e;
+        });
+        if (status.status === 'prove-failed') {
+            throw new ProveFailedError(jobId, status.error ?? 'unknown error', options.challenge, options.roots);
+        }
+        return base64ToBytes(status.proof ?? '');
+    }
     /**
      * Run one audit round against a pre-fetched setup.
      *
@@ -213,6 +237,10 @@ export class PinionProverClient {
      * const result = await client.audit(keyId, setup, { challengePct: 100 });
      * ```
      *
+     * Waits for the proof with no default deadline — pass `options.signal` if
+     * you want to cancel or bound how long this waits (e.g.
+     * `AbortSignal.timeout(60_000)` for the old fixed ceiling).
+     *
      * Throws `PinNotActiveError` if any challenged root is no longer pinned.
      */
     async audit(keyId, setup, options = {}) {
@@ -231,14 +259,28 @@ export class PinionProverClient {
             throw new Error('no blocks to audit');
         const challengeSize = Math.max(1, Math.round((challengePct / 100) * allBlockIds.length));
         const challenge = buildChallenge(challengeSize, allBlockIds.length);
-        const proofBytes = await this.prove(keyId, targetRoots, challenge);
+        const submission = await this.prove(keyId, targetRoots, challenge);
+        const proofBytes = await this.waitForProve(submission.jobId, {
+            pollIntervalMs: options.pollIntervalMs,
+            signal: options.signal,
+            challenge,
+            roots: targetRoots,
+            onStatus: options.onStatus,
+        });
         const verification = verifyProofResult({
             clientSetup: setup.clientSetup,
             blockIds: allBlockIds,
             challenge,
             proofBytes,
         });
-        return { pass: verification.verified, verification, blocksChecked: challengeSize, keyId, roots: targetRoots };
+        return {
+            pass: verification.verified,
+            verification,
+            blocksChecked: challengeSize,
+            keyId,
+            roots: targetRoots,
+            challenge,
+        };
     }
     // ---------------------------------------------------------------------------
     // HTTP helpers
@@ -310,6 +352,57 @@ async function parseJsonBody(resp) {
     }
 }
 // ---------------------------------------------------------------------------
+// Shared polling loop for waitForProve()/waitForTag()
+// ---------------------------------------------------------------------------
+/**
+ * Internal signal that a poll loop was cancelled via its caller-supplied
+ * AbortSignal before the job reached a terminal state. waitForProve()/
+ * waitForTag() catch this and rethrow as ProveTimeoutError/TagTimeoutError
+ * carrying lastStatus — never thrown to the outside on its own.
+ */
+class PollAbortedError extends Error {
+    lastStatus;
+    constructor(lastStatus) {
+        super('poll aborted');
+        this.lastStatus = lastStatus;
+        this.name = 'PollAbortedError';
+    }
+}
+/**
+ * Polls fetchStatus() every pollIntervalMs until isTerminal(status) is
+ * true, calling onTick(status) after every poll (terminal or not) so
+ * callers can drive progress callbacks. Has NO built-in deadline — the
+ * caller's polling budget is unlimited unless `signal` is given, in which
+ * case an abort rejects with PollAbortedError(lastStatus) instead of
+ * resolving.
+ */
+async function pollUntilTerminal(opts) {
+    let last;
+    for (;;) {
+        if (opts.signal?.aborted)
+            throw new PollAbortedError(last);
+        const status = await opts.fetchStatus();
+        last = status;
+        opts.onTick?.(status);
+        if (opts.isTerminal(status))
+            return status;
+        await sleepOrAbort(opts.pollIntervalMs, opts.signal, last);
+    }
+}
+function sleepOrAbort(ms, signal, lastStatus) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new PollAbortedError(lastStatus));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new PollAbortedError(lastStatus));
+        }, { once: true });
+    });
+}
+// ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
 export class ProverError extends Error {
@@ -355,7 +448,7 @@ export class PinNotActiveError extends Error {
         this.name = 'PinNotActiveError';
     }
 }
-/** Thrown by tag() when the async tag job reaches the "tag-failed" state. */
+/** Thrown by waitForTag() when the async tag job reaches the "tag-failed" state. */
 export class TagFailedError extends Error {
     jobId;
     reason;
@@ -366,7 +459,12 @@ export class TagFailedError extends Error {
         this.name = 'TagFailedError';
     }
 }
-/** Thrown by tag() when the job hasn't reached a terminal state within the configured timeout. */
+/**
+ * Thrown by waitForTag() when its `options.signal` fires before the job
+ * reaches a terminal state. There is no default deadline anymore — this
+ * only happens if the caller opted into one (e.g. `signal:
+ * AbortSignal.timeout(ms)`).
+ */
 export class TagTimeoutError extends Error {
     jobId;
     lastStatus;
@@ -377,25 +475,42 @@ export class TagTimeoutError extends Error {
         this.name = 'TagTimeoutError';
     }
 }
-/** Thrown by prove() when the async proof job reaches the "prove-failed" state. */
+/** Thrown by waitForProve() when the async proof job reaches the "prove-failed" state. */
 export class ProveFailedError extends Error {
     jobId;
     reason;
-    constructor(jobId, reason) {
+    challenge;
+    roots;
+    constructor(jobId, reason, 
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    challenge, roots) {
         super(`prove job ${jobId} failed: ${reason}`);
         this.jobId = jobId;
         this.reason = reason;
+        this.challenge = challenge;
+        this.roots = roots;
         this.name = 'ProveFailedError';
     }
 }
-/** Thrown by prove() when the job hasn't reached a terminal state within the configured timeout. */
+/**
+ * Thrown by waitForProve() when its `options.signal` fires before the job
+ * reaches a terminal state. There is no default deadline anymore — this
+ * only happens if the caller opted into one (e.g. `signal:
+ * AbortSignal.timeout(ms)`).
+ */
 export class ProveTimeoutError extends Error {
     jobId;
     lastStatus;
-    constructor(jobId, lastStatus) {
+    challenge;
+    roots;
+    constructor(jobId, lastStatus, 
+    /** The challenge this job was for — base64(JSON(WireChallenge)), decode with decodeChallenge(). Undefined if the caller didn't pass one to waitForProve(). */
+    challenge, roots) {
         super(`prove job ${jobId} timed out (last status: ${lastStatus})`);
         this.jobId = jobId;
         this.lastStatus = lastStatus;
+        this.challenge = challenge;
+        this.roots = roots;
         this.name = 'ProveTimeoutError';
     }
 }