docs: measure the runtime and the generated client modules

Adds a per-subsystem measurement of reactive.js, made by minifying it
repeatedly with one subsystem removed rather than counting source bytes.

This corrects the earlier audit on both figures and on the conclusion drawn
from them. Component controllers are 23,722 bytes minified / 6,660 gzipped --
30.6% of transfer, not the "about 18%" previously claimed -- and splitting them
out saves 6.6 kB gzipped on a typical page, not "3-4 kB". Measured against the
example app, / and /login use none of the ten controllers and /layout uses one,
so most pages download and parse the lot for nothing.

The larger finding is that the runtime is not where the weight is. One page
parses 490,212 decoded bytes across 11 generated client modules while
transferring 21,026, and the largest module is 89.8% duplicated lines: the
state-restore prologue appears 162 times because client-codegen.ts inlines the
sync into every peer alias of every client function. Gzip hides it on the wire,
but parse cost follows decoded bytes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/rpc/src/client.ts

@@ -66,7 +66,11 @@ export function serviceClient<Procedures extends AnyProcedures>(
         const callPromise = options.transport.call(
           { app, service: contract.name, procedure: property },
           input,
-          { signal: controller.signal, ...(identity ? { identity } : {}) },
+          {
+            signal: controller.signal,
+            idempotent: contract.procedures[property as keyof Procedures].idempotent === true,
+            ...(identity ? { identity } : {}),
+          },
         );
         try {
           const result = await Promise.race([callPromise, timeout]);

packages/rpc/src/index.ts

@@ -31,8 +31,14 @@ export {
 } from "./identity.ts";
 export type { ExportOptions, ImportOptions, SubjectContext } from "./identity.ts";
 
-export { inProcessTransport } from "./transport.ts";
-export type { CallOptions, InProcessHandler, RpcTarget, Transport } from "./transport.ts";
+export { inProcessTransport, retryingTransport } from "./transport.ts";
+export type {
+  CallOptions,
+  InProcessHandler,
+  RetryTransportOptions,
+  RpcTarget,
+  Transport,
+} from "./transport.ts";
 export { implement } from "./server.ts";
 export type {
   HandlerContext,

packages/rpc/src/transport.ts

@@ -10,12 +10,96 @@ export interface RpcTarget {
 export interface CallOptions {
   signal?: AbortSignal;
   identity?: string;
+  /** Supplied from the declared procedure; only these calls may be retried. */
+  idempotent?: boolean;
 }
 
 export interface Transport {
   call(target: RpcTarget, payload: unknown, options: CallOptions): Promise<ServiceResult>;
 }
 
+export interface RetryTransportOptions {
+  /** Retries after the initial attempt. Default: 2. */
+  retries?: number;
+  /** Initial exponential-backoff delay in milliseconds. Default: 50. */
+  backoffMs?: number;
+  /** Consecutive retryable failures before the target circuit opens. Default: 3. */
+  circuitFailureThreshold?: number;
+  /** How long an open circuit rejects calls before one probe is allowed. Default: 5s. */
+  circuitCooldownMs?: number;
+  now?: () => number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+function targetKey(target: RpcTarget): string {
+  return `${target.app}/${target.service}/${target.procedure}`;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}
+
+/**
+ * Add bounded retry and a per-procedure circuit breaker to any transport.
+ * The idempotency bit comes from the contract and is not caller-controlled.
+ */
+export function retryingTransport(base: Transport, options: RetryTransportOptions = {}): Transport {
+  const retries = options.retries ?? 2;
+  const backoffMs = options.backoffMs ?? 50;
+  const threshold = options.circuitFailureThreshold ?? 3;
+  const cooldownMs = options.circuitCooldownMs ?? 5_000;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  if (!Number.isInteger(retries) || retries < 0)
+    throw new RangeError("rpc retries must be a non-negative integer");
+  if (!Number.isFinite(backoffMs) || backoffMs < 0)
+    throw new RangeError("rpc backoffMs must be non-negative");
+  if (!Number.isInteger(threshold) || threshold < 1)
+    throw new RangeError("rpc circuitFailureThreshold must be positive");
+  if (!Number.isFinite(cooldownMs) || cooldownMs < 1)
+    throw new RangeError("rpc circuitCooldownMs must be positive");
+
+  const circuits = new Map<string, { failures: number; openUntil: number }>();
+  return {
+    async call(target, payload, callOptions) {
+      const key = targetKey(target);
+      const circuit = circuits.get(key);
+      if (circuit && circuit.openUntil > now()) {
+        return failure(RPC_ERROR_CODES.transport, "Service temporarily unavailable");
+      }
+      if (circuit?.openUntil) circuits.delete(key); // cooldown: allow one probe
+
+      const attempts = callOptions.idempotent ? retries + 1 : 1;
+      let result: ServiceResult = failure(RPC_ERROR_CODES.transport, "Service unreachable");
+      for (let attempt = 0; attempt < attempts; attempt++) {
+        if (callOptions.signal?.aborted) return failure(RPC_ERROR_CODES.transport, "Call aborted");
+        result = await base.call(target, payload, callOptions);
+        if (result.ok || !result.retryable) {
+          if (result.ok) circuits.delete(key);
+          return result;
+        }
+        if (attempt + 1 < attempts) await sleep(backoffMs * 2 ** attempt, callOptions.signal);
+      }
+      const failures = (circuits.get(key)?.failures ?? 0) + 1;
+      circuits.set(key, {
+        failures,
+        openUntil: failures >= threshold ? now() + cooldownMs : 0,
+      });
+      return result;
+    },
+  };
+}
+
 export type InProcessHandler = (
   payload: unknown,
   identity?: string,

packages/rpc/test/retry.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RPC_ERROR_CODES,
+  failure,
+  retryingTransport,
+  success,
+  type Transport,
+} from "../src/index.ts";
+
+function failingTransport(): { transport: Transport; calls: () => number } {
+  let count = 0;
+  return {
+    transport: {
+      async call() {
+        count++;
+        return failure(RPC_ERROR_CODES.transport, "down");
+      },
+    },
+    calls: () => count,
+  };
+}
+
+describe("retryingTransport", () => {
+  test("retries only declared idempotent calls", async () => {
+    const retryable = failingTransport();
+    const write = failingTransport();
+    const options = { retries: 2, backoffMs: 0 };
+    await retryingTransport(retryable.transport, options).call(
+      { app: "billing", service: "invoice", procedure: "get" },
+      {},
+      { idempotent: true },
+    );
+    await retryingTransport(write.transport, options).call(
+      { app: "billing", service: "invoice", procedure: "create" },
+      {},
+      { idempotent: false },
+    );
+    expect(retryable.calls()).toBe(3);
+    expect(write.calls()).toBe(1);
+  });
+
+  test("opens a circuit after repeated exhausted failures and recovers after cooldown", async () => {
+    let clock = 0;
+    let calls = 0;
+    const base: Transport = {
+      async call() {
+        calls++;
+        return calls < 3 ? failure(RPC_ERROR_CODES.transport, "down") : success("ok");
+      },
+    };
+    const transport = retryingTransport(base, {
+      retries: 0,
+      circuitFailureThreshold: 2,
+      circuitCooldownMs: 10,
+      now: () => clock,
+    });
+    const target = { app: "billing", service: "invoice", procedure: "get" };
+    await transport.call(target, {}, { idempotent: true });
+    await transport.call(target, {}, { idempotent: true });
+    expect(await transport.call(target, {}, { idempotent: true })).toMatchObject({
+      ok: false,
+      code: RPC_ERROR_CODES.transport,
+    });
+    expect(calls).toBe(2);
+    clock = 11;
+    expect(await transport.call(target, {}, { idempotent: true })).toEqual(success("ok"));
+  });
+});