@freqhole/api-client 0.2.14 → 0.3.1

package/src/CharnelTransport.ts

@@ -3,13 +3,10 @@
 // uses Tauri IPC commands to make P2P requests via the server's
 // app iroh endpoint. no WASM needed.
 
-import type { BlobData, Transport, TransportResponse } from "./transport.js";
-import type {
-  CloseReason,
-  EventFilter,
-  JobEvent,
-  JobStateSnapshot,
-} from "./codegen/schema.js";
+import type { BlobData, BlobFetchOptions, Transport, TransportResponse } from "./transport.js";
+import type { BlobProgressCallback } from "./WasmTransport.js";
+import { isTauriRuntime } from "./tauriRuntime.js";
+import type { CloseReason, EventFilter, JobEvent, JobStateSnapshot } from "./codegen/schema.js";
 import { JobEventsStreamClosed } from "./CharnelLocalTransport.js";
 
 // tauri invoke function type
@@ -21,6 +18,124 @@ function cacheKey(blobId: string): string {
   return `https://blob.local/${blobId}`;
 }
 
+/**
+ * error thrown by request()/upload methods when a tauri IPC call fails.
+ * mirrors sendToRemote.ts's `EnvelopeError` shape so callers can
+ * consistently check `.errorType` regardless of which transport produced
+ * the failure. `step` distinguishes which part of a two-step upload
+ * (local import vs. telling the remote peer to pull) failed.
+ */
+export class TransportError extends Error {
+  readonly errorType?: string;
+  readonly step?: "import" | "remote_trigger";
+  /**
+   * per-step breakdown for a multi-step fallback chain (e.g.
+   * `fetchBlob`'s verified-download -> api-request -> on-demand-blake3
+   * sequence). populated only by call sites that actually fall through
+   * multiple attempts before failing - absent for single-shot failures.
+   */
+  readonly attempts?: Array<{ step: string; reason: string }>;
+  constructor(
+    message: string,
+    opts?: {
+      errorType?: string;
+      step?: "import" | "remote_trigger";
+      attempts?: Array<{ step: string; reason: string }>;
+    },
+  ) {
+    super(message);
+    this.name = "TransportError";
+    this.errorType = opts?.errorType;
+    this.step = opts?.step;
+    this.attempts = opts?.attempts;
+  }
+}
+
+/**
+ * extract a best-effort `error_type` out of a caught tauri IPC
+ * rejection. tauri rejections are sometimes a plain string, sometimes an
+ * `Error`, and (once the rust side lands the convention - see
+ * docs/error-handling-tasks.md track P0-D) sometimes a short
+ * machine-parseable prefix like `"file_not_found: could not open file"`,
+ * or a JSON-encoded structured error body forwarded from a remote peer's
+ * response. this parses either shape, falling back to the raw message
+ * when neither is present - never matches on natural-language message
+ * text (the prefix regex only matches a single snake_case token
+ * immediately before the colon, so an ordinary sentence like "failed to
+ * open file: permission denied" is left alone).
+ */
+// P2P `ApiRequest` messages are read in one shot on the remote peer and
+// capped by that peer's configured `federation.max_message_size_mb`
+// (10 MB by default - see grimoire/src/config.rs). the base64 fallback
+// (used here when a blob-pull upload path isn't available for this
+// route, e.g. video uploads today) embeds the whole file directly in
+// that message, inflated ~4/3 by base64 plus a small JSON envelope. we
+// don't know the actual remote's configured cap, so this is a
+// conservative pre-flight check against the documented default with
+// headroom for that overhead - it exists purely to fail fast with a
+// clear message instead of a raw mid-transfer "stream too long"/generic
+// "network error".
+const MAX_BASE64_UPLOAD_BYTES = 7 * 1024 * 1024;
+
+function uploadTooLargeError(file: File, path: string): TransportError {
+  const mb = (file.size / (1024 * 1024)).toFixed(1);
+  const limitMb = (MAX_BASE64_UPLOAD_BYTES / (1024 * 1024)).toFixed(0);
+  const kind = path.includes("/video") ? "video uploads" : "uploads of this size";
+  return new TransportError(
+    `this file is ${mb} MB, too large to upload over this P2P connection (roughly ${limitMb} MB limit) - large ${kind} aren't fully supported over P2P yet`,
+    { errorType: "upload_too_large_for_transport" },
+  );
+}
+
+function extractErrorType(err: unknown): { message: string; errorType?: string } {
+  const message = err instanceof Error ? err.message : String(err);
+  const trimmed = message.trim();
+
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      const firstError =
+        Array.isArray(parsed.errors) && parsed.errors.length > 0
+          ? (parsed.errors[0] as Record<string, unknown>)
+          : undefined;
+      const errorType =
+        (typeof firstError?.error_type === "string" && firstError.error_type) ||
+        (typeof parsed.error_type === "string" && parsed.error_type) ||
+        undefined;
+      if (errorType) {
+        const detail =
+          (typeof firstError?.detail === "string" && firstError.detail) ||
+          (typeof parsed.message === "string" && parsed.message) ||
+          message;
+        return { message: detail, errorType };
+      }
+    } catch {
+      // not valid json, fall through to prefix-token parsing below
+    }
+  }
+
+  const prefixMatch = /^([a-z][a-z0-9_]*):\s*(.+)$/s.exec(message);
+  if (prefixMatch) {
+    return { message: prefixMatch[2], errorType: prefixMatch[1] };
+  }
+
+  return { message };
+}
+
+/** run `fn`, retagging any thrown error with which upload step failed. */
+async function tagStep<T>(step: "import" | "remote_trigger", fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e instanceof TransportError) {
+      throw new TransportError(e.message, { errorType: e.errorType, step });
+    }
+    const { message, errorType } = extractErrorType(e);
+    const stepLabel = step === "import" ? "local import" : "remote trigger";
+    throw new TransportError(`${stepLabel} failed: ${message}`, { errorType, step });
+  }
+}
+
 // tauri invoke is dynamically imported to avoid bundling in browser builds
 let invoke: InvokeFn | null = null;
 
@@ -43,7 +158,7 @@ async function ensureInvoke(): Promise<InvokeFn> {
  * check if tauri is available
  */
 export function isCharnelAvailable(): boolean {
-  return typeof window !== "undefined" && "__TAURI__" in window;
+  return isTauriRuntime();
 }
 
 // default cache name if none provided
@@ -120,11 +235,7 @@ export class CharnelTransport implements Transport {
   /**
    * make an API request via P2P
    */
-  async request(
-    method: string,
-    path: string,
-    body?: string,
-  ): Promise<TransportResponse> {
+  async request(method: string, path: string, body?: string): Promise<TransportResponse> {
     const inv = await ensureInvoke();
 
     // intentionally no per-error debug log here: the underlying
@@ -133,24 +244,33 @@ export class CharnelTransport implements Transport {
     // whether to surface the error. logging at this layer fires once
     // per request per failed peer and drowns the console for any
     // peer that's temporarily unreachable.
-    const result = (await inv("p2p_api_call", {
-      peerAddr: this.peerAddr,
-      method,
-      path,
-      body: body ?? null,
-    })) as { status: number; body: string };
-
-    return result;
+    try {
+      const result = (await inv("p2p_api_call", {
+        peerAddr: this.peerAddr,
+        method,
+        path,
+        body: body ?? null,
+      })) as { status: number; body: string };
+
+      return result;
+    } catch (e) {
+      const { message, errorType } = extractErrorType(e);
+      throw new TransportError(`p2p request failed: ${message}`, { errorType });
+    }
   }
 
   /**
    * upload via P2P
    *
-   * for music uploads, returns an error directing callers to use uploadByPath()
-   * which uses iroh-blobs pull model (file path -> FsStore import -> remote pull).
-   * for non-music uploads (images), uses base64 encoding (small enough to be fine).
+   * for music/video uploads, uses the iroh-blobs pull model (import bytes ->
+   * FsStore -> remote pull) - see uploadByPath() for the filesystem-path variant.
+   * for other uploads (images), uses base64 encoding (small enough to be fine).
    */
-  async upload(path: string, formData: FormData): Promise<TransportResponse> {
+  async upload(
+    path: string,
+    formData: FormData,
+    onProgress?: (loaded: number, total: number) => void,
+  ): Promise<TransportResponse> {
     // extract file from form data
     const file = formData.get("file") as File | null;
     if (!file) {
@@ -170,14 +290,16 @@ export class CharnelTransport implements Transport {
       };
     }
 
-    // for music uploads, import bytes into iroh-blobs store and use the
+    // for music/video uploads, import bytes into iroh-blobs store and use the
     // blake3 pull model (same as uploadByPath but from in-memory bytes).
     // this supports Android where file picker returns File objects, not paths.
-    if (path === "/api/upload/music") {
-      return this.uploadMusicViaBytes(file);
+    // the import is already chunked (see uploadMediaViaBytes), so real
+    // per-chunk progress is reported here, same as HttpTransport's XHR path.
+    if (path === "/api/upload/music" || path === "/api/upload/video") {
+      return this.uploadMediaViaBytes(path, file, onProgress);
     }
 
-    // for non-music uploads (images etc), use base64 (small enough)
+    // for non-media uploads (images etc), use base64 (small enough)
     return this.uploadViaBase64(path, file, formData);
   }
 
@@ -195,30 +317,31 @@ export class CharnelTransport implements Transport {
   ): Promise<TransportResponse> {
     const inv = await ensureInvoke();
 
-    // only use iroh-blobs for music uploads
-    if (path === "/api/upload/music") {
+    // only use iroh-blobs for music/video uploads
+    if (path === "/api/upload/music" || path === "/api/upload/video") {
       console.debug("[P2P] uploadByPath: importing blob from", filePath);
       // import file into local FsStore -> get blake3 hash
-      const blake3 = (await inv("p2p_import_blob", { filePath })) as string;
+      const blake3 = await tagStep(
+        "import",
+        async () => (await inv("p2p_import_blob", { filePath })) as string,
+      );
       console.debug("[P2P] uploadByPath: imported blob, blake3 =", blake3);
 
+      const defaultName = path === "/api/upload/video" ? "video" : "music";
       // build request body for the remote peer
       const body: Record<string, unknown> = {
         blake3,
-        filename:
-          filePath.split("/").pop() || filePath.split("\\").pop() || "music",
+        filename: filePath.split("/").pop() || filePath.split("\\").pop() || defaultName,
         ...metadata,
       };
 
       // tell the remote peer to pull the blob from us
-      return this.request(
-        "POST",
-        "/api/upload/music-by-blake3",
-        JSON.stringify(body),
+      return tagStep("remote_trigger", () =>
+        this.request("POST", `${path}-by-blake3`, JSON.stringify(body)),
       );
     }
 
-    // for non-music uploads, send path + metadata via api_request
+    // for non-media uploads, send path + metadata via api_request
     const body: Record<string, unknown> = {
       file_path: filePath,
       ...metadata,
@@ -235,6 +358,10 @@ export class CharnelTransport implements Transport {
     file: File,
     formData: FormData,
   ): Promise<TransportResponse> {
+    if (file.size > MAX_BASE64_UPLOAD_BYTES) {
+      throw uploadTooLargeError(file, path);
+    }
+
     const bytes = new Uint8Array(await file.arrayBuffer());
     const base64 = bytesToBase64(bytes);
 
@@ -258,7 +385,7 @@ export class CharnelTransport implements Transport {
   }
 
   /**
-   * upload music via in-memory bytes using iroh-blobs pull model
+   * upload music or video via in-memory bytes using iroh-blobs pull model
    *
    * streams the File to the local blobs store in bounded chunks via
    * p2p_import_begin / p2p_import_chunk / p2p_import_finish, then tells the
@@ -266,45 +393,55 @@ export class CharnelTransport implements Transport {
    * tauri IPC is JSON-only and a single large base64 payload OOMs the
    * webview; it also keeps memory bounded on both sides (the receiver
    * accumulates chunks in a temp file on disk, not in memory).
+   *
+   * `onProgress`, if given, is called after each chunk finishes uploading
+   * with (bytes sent so far, file.size) - this is real, byte-level progress
+   * driven by the same chunk loop that does the actual IPC transfer, not an
+   * estimate. only covers the local-import phase (client -> local FsStore);
+   * the remote peer's own pull afterwards has no progress signal exposed
+   * back to this client.
    */
-  private async uploadMusicViaBytes(
+  private async uploadMediaViaBytes(
+    path: string,
     file: File,
+    onProgress?: (loaded: number, total: number) => void,
   ): Promise<TransportResponse> {
     const inv = await ensureInvoke();
 
-    console.debug("[P2P] uploadMusicViaBytes: streaming file", file.name, file.size, "bytes");
+    console.debug("[P2P] uploadMediaViaBytes: streaming file", file.name, file.size, "bytes");
 
     // ~4MB raw per chunk -> ~5.5MB base64 per IPC call, well within limits.
     const CHUNK_SIZE = 4 * 1024 * 1024;
 
-    const uploadId = (await inv("p2p_import_begin")) as string;
-    try {
-      for (let offset = 0; offset < file.size; offset += CHUNK_SIZE) {
-        const slice = file.slice(offset, Math.min(offset + CHUNK_SIZE, file.size));
-        const chunkBytes = new Uint8Array(await slice.arrayBuffer());
-        const b64 = bytesToBase64(chunkBytes);
-        await inv("p2p_import_chunk", { uploadId, data: b64 });
-      }
-    } catch (err) {
-      // best-effort cleanup of the partial temp file on the receiver side.
+    const blake3 = await tagStep("import", async () => {
+      const uploadId = (await inv("p2p_import_begin")) as string;
       try {
-        await inv("p2p_import_abort", { uploadId });
-      } catch {
-        // ignore abort failures
+        for (let offset = 0; offset < file.size; offset += CHUNK_SIZE) {
+          const slice = file.slice(offset, Math.min(offset + CHUNK_SIZE, file.size));
+          const chunkBytes = new Uint8Array(await slice.arrayBuffer());
+          const b64 = bytesToBase64(chunkBytes);
+          await inv("p2p_import_chunk", { uploadId, data: b64 });
+          onProgress?.(Math.min(offset + chunkBytes.length, file.size), file.size);
+        }
+      } catch (err) {
+        // best-effort cleanup of the partial temp file on the receiver side.
+        try {
+          await inv("p2p_import_abort", { uploadId });
+        } catch {
+          // ignore abort failures
+        }
+        throw err;
       }
-      throw err;
-    }
 
-    // finalize: import accumulated temp file into the blobs store -> blake3.
-    const blake3 = (await inv("p2p_import_finish", { uploadId })) as string;
-    console.debug("[P2P] uploadMusicViaBytes: imported blob, blake3 =", blake3);
+      // finalize: import accumulated temp file into the blobs store -> blake3.
+      return (await inv("p2p_import_finish", { uploadId })) as string;
+    });
+    console.debug("[P2P] uploadMediaViaBytes: imported blob, blake3 =", blake3);
 
     // tell the remote peer to pull the blob from us
     const body = { blake3, filename: file.name };
-    return this.request(
-      "POST",
-      "/api/upload/music-by-blake3",
-      JSON.stringify(body),
+    return tagStep("remote_trigger", () =>
+      this.request("POST", `${path}-by-blake3`, JSON.stringify(body)),
     );
   }
 
@@ -318,20 +455,37 @@ export class CharnelTransport implements Transport {
     const inv = await ensureInvoke();
     const tauri = await import("@tauri-apps/api/core");
     const onProgress = new tauri.Channel<{ bytes_downloaded: number }>();
+    // per-step failure breakdown, attached to the final thrown error so a
+    // bug report/log has the full fallback-chain picture, not just the
+    // last step's message (see docs/error-handling-tasks.md track P0-E).
+    const attempts: Array<{ step: string; reason: string }> = [];
 
     if (blake3) {
-      // blake3 known — use verified iroh-blobs download
-      const result = (await inv("p2p_fetch_blob_verified", {
-        peerAddr: this.peerAddr,
-        blake3Hash: blake3,
-        onProgress,
-      })) as { data: string; content_type: string | null; size: number };
-
-      const bytes = base64ToBytes(result.data);
-      return {
-        data: bytes,
-        contentType: result.content_type ?? "audio/mpeg",
-      };
+      // blake3 known — use verified iroh-blobs download. no fallback
+      // chain in this branch (no blake3 means we can't retry via
+      // api_request/on-demand-blake3 below), but still tag the failure
+      // with `attempts` for consistency with the no-blake3 path.
+      try {
+        const result = (await inv("p2p_fetch_blob_verified", {
+          peerAddr: this.peerAddr,
+          blake3Hash: blake3,
+          onProgress,
+        })) as { data: string; content_type: string | null; size: number };
+
+        const bytes = base64ToBytes(result.data);
+        return {
+          data: bytes,
+          contentType: result.content_type ?? "audio/mpeg",
+        };
+      } catch (e) {
+        const { message, errorType } = extractErrorType(e);
+        throw new TransportError(`verified download failed for blob ${blobId}: ${message}`, {
+          errorType,
+          attempts: [
+            { step: "verified_download", reason: errorType ? `${errorType}: ${message}` : message },
+          ],
+        });
+      }
     }
 
     // no blake3 — try api_request to get blob data from database
@@ -345,38 +499,120 @@ export class CharnelTransport implements Transport {
           const contentType = parsed.data.mime || "application/octet-stream";
           return { data: bytes, contentType };
         }
+        attempts.push({
+          step: "api_request",
+          reason: `unexpected response shape (status ${result.status})`,
+        });
+      } else {
+        attempts.push({ step: "api_request", reason: `http ${result.status}` });
       }
     } catch (e) {
-      const errorMessage = e instanceof Error ? e.message : String(e);
+      const { message, errorType } = extractErrorType(e);
+      const reason = errorType ? `${errorType}: ${message}` : message;
+      attempts.push({ step: "api_request", reason });
       console.warn(
-        `[CharnelTransport] api blob data request failed, falling back to verified download: ${errorMessage}`,
+        `[CharnelTransport] api blob data request failed, falling back to verified download: ${reason}`,
       );
     }
 
     // fallback: ask the peer to compute blake3, then do verified download
-    const result = (await inv("p2p_fetch_blob_verified_by_id", {
-      peerAddr: this.peerAddr,
-      blobId,
-      onProgress,
-    })) as {
-      data: string;
-      content_type: string | null;
-      size: number;
-      blake3: string;
-    };
+    try {
+      const result = (await inv("p2p_fetch_blob_verified_by_id", {
+        peerAddr: this.peerAddr,
+        blobId,
+        onProgress,
+      })) as {
+        data: string;
+        content_type: string | null;
+        size: number;
+        blake3: string;
+      };
+
+      const bytes = base64ToBytes(result.data);
+      return {
+        data: bytes,
+        contentType: result.content_type ?? "application/octet-stream",
+      };
+    } catch (e) {
+      const { message, errorType } = extractErrorType(e);
+      attempts.push({
+        step: "on_demand_blake3",
+        reason: errorType ? `${errorType}: ${message}` : message,
+      });
+      throw new TransportError(
+        `failed to fetch blob ${blobId} after trying all fallback methods: ${message}`,
+        { errorType, attempts },
+      );
+    }
+  }
 
-    const bytes = base64ToBytes(result.data);
-    return {
-      data: bytes,
-      contentType: result.content_type ?? "application/octet-stream",
+  /**
+   * fetch a blob via P2P, reporting download progress.
+   *
+   * only the verified (blake3) iroh-blobs path can report progress - the
+   * rust side streams `bytes_downloaded` over a tauri Channel. without a
+   * blake3 there is nothing to subscribe to, so this degrades to a plain
+   * `fetchBlob` and a single 100% report at the end.
+   *
+   * `totalBytes` must be supplied by the caller (blob metadata lookup):
+   * the channel only carries a running byte count, not the total.
+   */
+  async fetchBlobWithProgress(
+    blobId: string,
+    onProgress: BlobProgressCallback,
+    blake3?: string,
+    totalBytes?: number,
+    mimeType?: string,
+  ): Promise<BlobData> {
+    const inv = await ensureInvoke();
+    const tauri = await import("@tauri-apps/api/core");
+    const channel = new tauri.Channel<{ bytes_downloaded: number }>();
+    channel.onmessage = (message) => {
+      const received = message?.bytes_downloaded ?? 0;
+      // a total of 0 keeps the ui on its indeterminate/bouncing state
+      // rather than reporting a bogus ratio
+      onProgress(received, totalBytes ?? 0);
     };
+
+    // most library blobs have no blake3 on the client (only synced/uploaded
+    // ones do). the by-id route makes the peer compute it and then streams
+    // the same verified download, so it reports real progress too - without
+    // this branch a blake3-less blob only ever reported a single 100% tick
+    // at the end, which reads as "no progress bar at all".
+    const command = blake3 ? "p2p_fetch_blob_verified" : "p2p_fetch_blob_verified_by_id";
+    const args = blake3
+      ? { peerAddr: this.peerAddr, blake3Hash: blake3, onProgress: channel }
+      : { peerAddr: this.peerAddr, blobId, onProgress: channel };
+
+    try {
+      const result = (await inv(command, args)) as {
+        data: string;
+        content_type: string | null;
+        size: number;
+      };
+
+      const bytes = base64ToBytes(result.data);
+      onProgress(bytes.byteLength, totalBytes || bytes.byteLength);
+      return {
+        data: bytes,
+        contentType: result.content_type ?? mimeType ?? "application/octet-stream",
+      };
+    } catch (e) {
+      const { message, errorType } = extractErrorType(e);
+      throw new TransportError(`verified download failed for blob ${blobId}: ${message}`, {
+        errorType,
+        attempts: [
+          { step: "verified_download", reason: errorType ? `${errorType}: ${message}` : message },
+        ],
+      });
+    }
   }
 
   /**
-   * get a URL for a blob - caches in Cache API
+   * get a URL for a blob - caches in Cache API unless `opts.cache === "skip"`
    * if blake3 provided, uses verified iroh-blobs download
    */
-  async getBlobUrl(blobId: string, blake3?: string): Promise<string> {
+  async getBlobUrl(blobId: string, blake3?: string, opts?: BlobFetchOptions): Promise<string> {
     // check in-memory cache first
     const cached = urlCache.get(blobId);
     if (cached) {
@@ -400,11 +636,13 @@ export class CharnelTransport implements Transport {
       type: blobData.contentType,
     });
 
-    // store in Cache API (HTTP URL key for webkitgtk compatibility)
-    const response = new Response(blob, {
-      headers: { "Content-Type": blobData.contentType },
-    });
-    await cache.put(cacheKey(blobId), response);
+    if (opts?.cache !== "skip") {
+      // store in Cache API (HTTP URL key for webkitgtk compatibility)
+      const response = new Response(blob, {
+        headers: { "Content-Type": blobData.contentType },
+      });
+      await cache.put(cacheKey(blobId), response);
+    }
 
     // create object URL
     const url = URL.createObjectURL(blob);
@@ -412,6 +650,58 @@ export class CharnelTransport implements Transport {
     return url;
   }
 
+  /**
+   * get a URL for a blob, reporting download progress along the way.
+   * same caching behaviour as `getBlobUrl` - a cache hit reports 100%
+   * immediately so callers can clear their loading state.
+   */
+  async getBlobUrlWithProgress(
+    blobId: string,
+    onProgress: BlobProgressCallback,
+    blake3?: string,
+    totalBytes?: number,
+    mimeType?: string,
+    opts?: BlobFetchOptions,
+  ): Promise<string> {
+    const cached = urlCache.get(blobId);
+    if (cached) {
+      onProgress(1, 1);
+      return cached;
+    }
+
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(cacheKey(blobId));
+    if (cachedResponse) {
+      const blob = await cachedResponse.blob();
+      const url = URL.createObjectURL(blob);
+      urlCache.set(blobId, url);
+      onProgress(1, 1);
+      return url;
+    }
+
+    const blobData = await this.fetchBlobWithProgress(
+      blobId,
+      onProgress,
+      blake3,
+      totalBytes,
+      mimeType,
+    );
+    const blob = new Blob([blobData.data.slice().buffer], {
+      type: blobData.contentType,
+    });
+
+    if (opts?.cache !== "skip") {
+      const response = new Response(blob, {
+        headers: { "Content-Type": blobData.contentType },
+      });
+      await cache.put(cacheKey(blobId), response);
+    }
+
+    const url = URL.createObjectURL(blob);
+    urlCache.set(blobId, url);
+    return url;
+  }
+
   /**
    * revoke a blob URL
    */
@@ -476,19 +766,14 @@ export class CharnelTransport implements Transport {
     return out;
   }
 
-  subscribeJobEvents(
-    filter?: EventFilter,
-    signal?: AbortSignal,
-  ): AsyncIterable<JobEvent> {
+  subscribeJobEvents(filter?: EventFilter, signal?: AbortSignal): AsyncIterable<JobEvent> {
     return charnelRemoteJobEventsIterable(this.peerAddr, filter, signal);
   }
 }
 
 // frame shape emitted by the rust-side `JobsEventsFrame` — mirrors
 // `CharnelLocalTransport.ts`.
-type JobsEventsFrame =
-  | { kind: "event"; evt: JobEvent }
-  | { kind: "closed"; reason: CloseReason };
+type JobsEventsFrame = { kind: "event"; evt: JobEvent } | { kind: "closed"; reason: CloseReason };
 
 async function* charnelRemoteJobEventsIterable(
   peerAddr: string,