@durable-effect/jobs 0.0.1-next.3 → 0.0.1-next.5

package/README.md

@@ -1,490 +1,603 @@
 # @durable-effect/jobs
 
-Durable jobs for Cloudflare Workers built on Effect. This package provides high-level abstractions for common durable patterns:
+Durable job abstractions for Cloudflare Workers built on [Effect](https://effect.website/). Write business logic as Effect programs while the framework handles durability, retries, and scheduling.
 
-- **Continuous** - Execute functions on a schedule (this guide)
-- **Debounce** - Accumulate events and flush on schedule/threshold (coming soon)
-- **WorkerPool** - Process events one at a time with retries (coming soon)
+## Overview
 
-## Installation
+This package provides three job types for different patterns:
 
-```bash
-npm install @durable-effect/jobs effect
-```
-
-## Continuous Primitive
-
-The Continuous primitive executes a function on a recurring schedule. Perfect for:
+| Job Type | Purpose | Use Cases |
+|----------|---------|-----------|
+| **Continuous** | Recurring work on a schedule | Token refresh, health checks, daily reports |
+| **Debounce** | Batch rapid events before processing | Webhook coalescing, update batching |
+| **Task** | Event-driven state machines | Order workflows, multi-step processes |
 
-- Token refresh
-- Periodic data sync
-- Health checks
-- Report generation
-- Cache warming
+Each job instance runs in its own Durable Object, providing:
+- Persistent state that survives restarts
+- Durable alarms for scheduling
+- Automatic retry with configurable backoff
+- Type-safe client with full inference
 
-### Quick Start
+## Quick Start
 
-```ts
+```typescript
 import { Effect, Schema } from "effect";
-import { Continuous, createDurableJobs } from "@durable-effect/jobs";
+import { createDurableJobs, Continuous } from "@durable-effect/jobs";
 
-// 1. Define your primitive (name comes from the object key in step 2)
+// 1. Define a job
 const tokenRefresher = Continuous.make({
-  // Schema for persistent state
   stateSchema: Schema.Struct({
     accessToken: Schema.String,
     refreshToken: Schema.String,
     expiresAt: Schema.Number,
   }),
-
-  // Execute every 30 minutes
   schedule: Continuous.every("30 minutes"),
-
-  // The function to run
   execute: (ctx) =>
     Effect.gen(function* () {
-      console.log(`Refreshing token (run #${ctx.runCount})`);
-
-      // Access current state
-      const { refreshToken } = ctx.state;
-
-      // Call your refresh API
-      const newTokens = yield* refreshTokens(refreshToken);
-
-      // Update state (persisted automatically)
-      ctx.setState({
-        accessToken: newTokens.access_token,
-        refreshToken: newTokens.refresh_token,
-        expiresAt: Date.now() + newTokens.expires_in * 1000,
-      });
+      const state = yield* ctx.state;
+      const newToken = yield* refreshAccessToken(state.refreshToken);
+      yield* ctx.setState({ ...state, accessToken: newToken, expiresAt: Date.now() + 1800000 });
     }),
 });
 
-// 2. Create the Durable Object and Client - keys become primitive names
-const { Jobs, JobsClient } = createDurableJobs({
-  tokenRefresher,
-});
+// 2. Create engine and client
+const { Jobs, JobsClient } = createDurableJobs({ tokenRefresher });
 
 // 3. Export the Durable Object class
 export { Jobs };
 
-// 4. Use in your worker
+// 4. Use the client in your worker
 export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const client = JobsClient.fromBinding(env.PRIMITIVES);
-
-    // Start a token refresher for a user (name matches the key from step 2)
-    await client.continuous("tokenRefresher").start({
-      id: "user-123",
-      input: {
-        accessToken: "",
-        refreshToken: "rt_initial_token",
-        expiresAt: 0,
-      },
-    });
-
-    return new Response("Token refresher started!");
+  async fetch(request: Request, env: Env) {
+    const client = JobsClient.fromBinding(env.JOBS);
+
+    await Effect.runPromise(
+      client.continuous("tokenRefresher").start({
+        id: "user-123",
+        input: { accessToken: "", refreshToken: "rt_abc", expiresAt: 0 },
+      })
+    );
+
+    return new Response("OK");
   },
 };
 ```
 
-### wrangler.toml Configuration
-
-```toml
-[[durable_objects.bindings]]
-name = "PRIMITIVES"
-class_name = "Jobs"
+Configure your `wrangler.jsonc`:
+
+```jsonc
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "src/worker.ts",
+  "compatibility_date": "2024-11-27",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "JOBS",
+        "class_name": "Jobs"
+      }
+    ]
+  },
 
-[[migrations]]
-tag = "v1"
-new_classes = ["Jobs"]
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_classes": ["Jobs"]
+    }
+  ]
+}
 ```
 
-## API Reference
+---
 
-### `Continuous.make(config)`
+## Defining Jobs
 
-Creates a continuous primitive definition. The name is assigned when you register
-the primitive via `createDurableJobs()` - the object key becomes the name.
+### Continuous Jobs
 
-```ts
-const myPrimitive = Continuous.make({
-  stateSchema: Schema.Struct({ ... }),
-  schedule: Continuous.every("1 hour"),
-  execute: (ctx) => Effect.succeed(undefined),
-});
+Execute on a fixed schedule. Best for recurring background work.
 
-// Name "myPrimitive" comes from the key
-const { Jobs, JobsClient } = createDurableJobs({
-  myPrimitive,
+```typescript
+import { Continuous } from "@durable-effect/jobs";
+import { Backoff } from "@durable-effect/core";
+
+const healthChecker = Continuous.make({
+  stateSchema: Schema.Struct({
+    lastCheckAt: Schema.Number,
+    consecutiveFailures: Schema.Number,
+  }),
+
+  // Schedule options
+  schedule: Continuous.every("5 minutes"),  // or Continuous.cron("0 */5 * * *")
+
+  // Execute immediately on start (default: true)
+  startImmediately: true,
+
+  // Optional retry configuration
+  retry: {
+    maxAttempts: 3,
+    delay: Backoff.exponential({ base: "1 second", max: "30 seconds" }),
+  },
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const state = yield* ctx.state;
+
+      // ctx provides rich metadata
+      console.log(`Run #${ctx.runCount}, attempt ${ctx.attempt}`);
+
+      const healthy = yield* checkHealth();
+      if (!healthy && state.consecutiveFailures > 10) {
+        // Terminate removes all state and cancels the schedule
+        return yield* ctx.terminate({ reason: "Too many failures" });
+      }
+
+      yield* ctx.updateState((s) => ({
+        lastCheckAt: Date.now(),
+        consecutiveFailures: healthy ? 0 : s.consecutiveFailures + 1,
+      }));
+    }),
 });
 ```
 
-#### Parameters
+**Context properties:**
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `config.stateSchema` | `Schema.Schema<S>` | Effect Schema for validating and serializing state |
-| `config.schedule` | `ContinuousSchedule` | When to execute (see Schedules below) |
-| `config.startImmediately` | `boolean` | Execute immediately on start (default: `true`) |
-| `config.execute` | `(ctx) => Effect<void, E, R>` | Function to execute on schedule |
-| `config.onError` | `(error, ctx) => Effect<void>` | Optional error handler |
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | `Effect<S>` | Current state (yields the value) |
+| `setState(s)` | `Effect<void>` | Replace entire state |
+| `updateState(fn)` | `Effect<void>` | Transform state |
+| `terminate(opts?)` | `Effect<never>` | Stop job and purge state |
+| `instanceId` | `string` | Unique DO instance ID |
+| `jobName` | `string` | Registered job name |
+| `runCount` | `number` | Execution count (1-indexed) |
+| `attempt` | `number` | Current retry attempt (1 = first try) |
+| `isRetry` | `boolean` | Whether this is a retry |
 
-### Schedules
+---
 
-#### `Continuous.every(interval)`
+### Debounce Jobs
 
-Execute at a fixed interval.
+Collect events and process them in batches. Flushes after a delay or when max events reached.
 
-```ts
-Continuous.every("30 minutes")
-Continuous.every("1 hour")
-Continuous.every("24 hours")
-Continuous.every(Duration.minutes(30))
-```
+```typescript
+import { Debounce } from "@durable-effect/jobs";
 
-#### `Continuous.cron(expression)` (coming soon)
+const webhookBatcher = Debounce.make({
+  // Schema for incoming events
+  eventSchema: Schema.Struct({
+    type: Schema.String,
+    contactId: Schema.String,
+    data: Schema.Unknown,
+  }),
 
-Execute based on a cron expression.
+  // Optional: separate state schema (defaults to eventSchema)
+  stateSchema: Schema.Struct({
+    events: Schema.Array(Schema.Unknown),
+    count: Schema.Number,
+  }),
 
-```ts
-// Every day at midnight
-Continuous.cron("0 0 * * *")
+  // Flush timing
+  flushAfter: "5 seconds",
+  maxEvents: 100,  // Optional: flush early if reached
 
-// Every Monday at 9am
-Continuous.cron("0 9 * * 1")
+  // Optional: custom event reducer (default: keep latest event)
+  onEvent: (ctx) =>
+    Effect.succeed({
+      events: [...ctx.state.events, ctx.event],
+      count: ctx.state.count + 1,
+    }),
 
-// Every hour
-Continuous.cron("0 * * * *")
+  // Process the batch
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const state = yield* ctx.state;
+      const count = yield* ctx.eventCount;
+
+      console.log(`Flushing ${count} events, reason: ${ctx.flushReason}`);
+      yield* sendWebhookBatch(state.events);
+    }),
+});
 ```
 
-### ContinuousContext
+**Execute context:**
 
-The context object passed to your `execute` function:
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | `Effect<S>` | Accumulated state |
+| `eventCount` | `Effect<number>` | Total events received |
+| `flushReason` | `string` | `"maxEvents"` \| `"flushAfter"` \| `"manual"` |
+| `debounceStartedAt` | `Effect<number>` | When first event arrived |
+| `attempt` | `number` | Retry attempt |
+| `isRetry` | `boolean` | Whether this is a retry |
 
-```ts
-interface ContinuousContext<S> {
-  // Current state (read-only reference)
-  readonly state: S;
+**Event context (onEvent):**
 
-  // Replace the entire state
-  readonly setState: (state: S) => void;
+| Property | Type | Description |
+|----------|------|-------------|
+| `event` | `I` | The incoming event |
+| `state` | `S` | Current accumulated state |
+| `eventCount` | `number` | Events so far |
+| `instanceId` | `string` | DO instance ID |
 
-  // Update state via function
-  readonly updateState: (fn: (current: S) => S) => void;
+---
 
-  // Unique instance identifier
-  readonly instanceId: string;
+### Task Jobs
 
-  // Number of times execute has been called
-  readonly runCount: number;
+User-controlled state machines. You decide when to schedule execution via events.
 
-  // Name of this primitive
-  readonly primitiveName: string;
-}
-```
+```typescript
+import { Task } from "@durable-effect/jobs";
+import { Duration } from "effect";
 
-### Client Methods
+const orderProcessor = Task.make({
+  stateSchema: Schema.Struct({
+    orderId: Schema.String,
+    status: Schema.Literal("pending", "processing", "shipped", "delivered"),
+    attempts: Schema.Number,
+  }),
 
-#### `client.continuous(name).start({ id, input })`
+  eventSchema: Schema.Union(
+    Schema.Struct({ _tag: Schema.Literal("OrderPlaced"), orderId: Schema.String }),
+    Schema.Struct({ _tag: Schema.Literal("PaymentReceived") }),
+    Schema.Struct({ _tag: Schema.Literal("Shipped"), trackingNumber: Schema.String }),
+  ),
 
-Start a continuous primitive instance.
+  // Handle incoming events
+  onEvent: (event, ctx) =>
+    Effect.gen(function* () {
+      switch (event._tag) {
+        case "OrderPlaced":
+          yield* ctx.setState({
+            orderId: event.orderId,
+            status: "pending",
+            attempts: 0,
+          });
+          yield* ctx.schedule(Duration.minutes(5)); // Check payment in 5 min
+          break;
+
+        case "PaymentReceived":
+          yield* ctx.updateState((s) => ({ ...s, status: "processing" }));
+          break;
+
+        case "Shipped":
+          yield* ctx.updateState((s) => ({ ...s, status: "shipped" }));
+          yield* ctx.schedule(Duration.hours(24)); // Check delivery tomorrow
+          break;
+      }
+    }),
 
-```ts
-const result = await client.continuous("tokenRefresher").start({
-  id: "user-123",           // Unique instance ID
-  input: { ... },           // Initial state (must match stateSchema)
-});
+  // Execute when alarm fires
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const state = yield* ctx.state;
+      if (!state) return;
+
+      if (state.status === "pending") {
+        // Still pending after 5 min - send reminder
+        yield* sendPaymentReminder(state.orderId);
+        yield* ctx.schedule(Duration.minutes(30)); // Check again
+      }
+
+      if (state.status === "shipped") {
+        const delivered = yield* checkDelivery(state.orderId);
+        if (delivered) {
+          yield* ctx.updateState((s) => ({ ...s, status: "delivered" }));
+          yield* ctx.terminate(); // Order complete
+        } else {
+          yield* ctx.schedule(Duration.hours(24)); // Check again tomorrow
+        }
+      }
+    }),
+
+  // Optional: handle idle state (no alarm scheduled)
+  onIdle: (ctx) =>
+    Effect.gen(function* () {
+      // Schedule cleanup in 1 hour
+      yield* ctx.schedule(Duration.hours(1));
+    }),
 
-// Result:
-// { _type: "continuous.start", instanceId: string, created: boolean, status: string }
+  // Optional: handle errors
+  onError: (error, ctx) =>
+    Effect.gen(function* () {
+      yield* Effect.logError("Task failed", error);
+      yield* ctx.updateState((s) => ({ ...s, attempts: s.attempts + 1 }));
+      yield* ctx.schedule(Duration.seconds(30)); // Retry
+    }),
+});
 ```
 
-If the instance already exists, returns `{ created: false }` with current status.
+**Event context (onEvent):**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | `Effect<S \| null>` | Current state (null if first event) |
+| `setState(s)` | `Effect<void>` | Set state |
+| `updateState(fn)` | `Effect<void>` | Transform state |
+| `schedule(when)` | `Effect<void>` | Schedule execution |
+| `cancelSchedule()` | `Effect<void>` | Cancel scheduled execution |
+| `getScheduledTime()` | `Effect<number \| null>` | Get scheduled time |
+| `terminate()` | `Effect<never>` | Terminate and purge state |
+| `isFirstEvent` | `boolean` | True if state was null |
+| `eventCount` | `Effect<number>` | Total events received |
+
+**Execute context:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state` | `Effect<S \| null>` | Current state |
+| `setState/updateState` | `Effect<void>` | Modify state |
+| `schedule/cancelSchedule` | `Effect<void>` | Control scheduling |
+| `terminate()` | `Effect<never>` | Terminate task |
+| `executeCount` | `Effect<number>` | Times execute has run |
+| `eventCount` | `Effect<number>` | Total events received |
+| `createdAt` | `Effect<number>` | Task creation time |
+
+---
 
-#### `client.continuous(name).stop(id, options?)`
+## Using the Client
 
-Stop a running instance.
+### Setup
 
-```ts
-const result = await client.continuous("tokenRefresher").stop("user-123", {
-  reason: "User logged out",  // Optional reason
+```typescript
+const { Jobs, JobsClient } = createDurableJobs({
+  tokenRefresher,
+  webhookBatcher,
+  orderProcessor,
 });
 
-// Result:
-// { _type: "continuous.stop", stopped: boolean, reason: string }
+// In your worker
+const client = JobsClient.fromBinding(env.JOBS);
 ```
 
-#### `client.continuous(name).trigger(id)`
+### Continuous Client
+
+```typescript
+// Start a job instance
+const result = yield* client.continuous("tokenRefresher").start({
+  id: "user-123",            // Instance identifier
+  input: { /* initial state */ },
+});
+// Returns: { created: boolean, instanceId: string, status: JobStatus }
 
-Manually trigger immediate execution (bypasses schedule).
+// Trigger immediate execution (bypass schedule)
+yield* client.continuous("tokenRefresher").trigger("user-123");
 
-```ts
-const result = await client.continuous("tokenRefresher").trigger("user-123");
+// Check status
+const status = yield* client.continuous("tokenRefresher").status("user-123");
+// Returns: { status: "running" | "stopped" | "not_found", runCount?, nextRunAt? }
 
-// Result:
-// { _type: "continuous.trigger", triggered: boolean }
+// Get current state
+const { state } = yield* client.continuous("tokenRefresher").getState("user-123");
+
+// Terminate (cancel alarm + delete all state)
+yield* client.continuous("tokenRefresher").terminate("user-123", {
+  reason: "User requested",
+});
 ```
 
-#### `client.continuous(name).status(id)`
+### Debounce Client
+
+```typescript
+// Add an event (creates instance if needed)
+const result = yield* client.debounce("webhookBatcher").add({
+  id: "contact-456",
+  event: { type: "contact.updated", contactId: "456", data: {} },
+});
+// Returns: { created: boolean, eventCount: number, willFlushAt: number | null }
+
+// Force immediate flush
+yield* client.debounce("webhookBatcher").flush("contact-456");
 
-Get current status of an instance.
+// Clear without processing
+yield* client.debounce("webhookBatcher").clear("contact-456");
 
-```ts
-const result = await client.continuous("tokenRefresher").status("user-123");
+// Check status
+const status = yield* client.debounce("webhookBatcher").status("contact-456");
+// Returns: { status: "debouncing" | "idle" | "not_found", eventCount?, willFlushAt? }
 
-// Result:
-// { _type: "continuous.status", status: string, runCount: number, nextRunAt?: number }
+// Get accumulated state
+const { state } = yield* client.debounce("webhookBatcher").getState("contact-456");
 ```
 
-#### `client.continuous(name).getState(id)`
+### Task Client
+
+```typescript
+// Send an event (creates instance if needed)
+const result = yield* client.task("orderProcessor").send({
+  id: "order-789",
+  event: { _tag: "OrderPlaced", orderId: "order-789" },
+});
+// Returns: { created: boolean, instanceId: string, scheduledAt: number | null }
 
-Get current state of an instance.
+// Trigger immediate execution
+yield* client.task("orderProcessor").trigger("order-789");
 
-```ts
-const result = await client.continuous("tokenRefresher").getState("user-123");
+// Check status
+const status = yield* client.task("orderProcessor").status("order-789");
+// Returns: { status: "active" | "idle" | "not_found", scheduledAt?, eventCount? }
 
-// Result:
-// { _type: "continuous.getState", state: S | null }
-```
+// Get state
+const { state, scheduledAt } = yield* client.task("orderProcessor").getState("order-789");
 
-## Error Handling
+// Terminate
+yield* client.task("orderProcessor").terminate("order-789");
+```
 
-### Using `onError`
+---
 
-Handle errors gracefully without failing the execution:
+## Common Concepts
 
-```ts
-const resilientPrimitive = Continuous.make({
-  stateSchema: Schema.Struct({
-    data: Schema.String,
-    errorCount: Schema.Number,
-    lastError: Schema.NullOr(Schema.String),
-  }),
-  schedule: Continuous.every("5 minutes"),
+### Instance IDs
 
-  execute: (ctx) =>
-    Effect.gen(function* () {
-      // This might fail
-      const data = yield* fetchExternalData();
-      ctx.updateState((s) => ({
-        ...s,
-        data,
-        errorCount: 0,
-        lastError: null,
-      }));
-    }),
+Each job instance is identified by a unique ID. The internal Durable Object instance ID follows the pattern:
 
-  onError: (error, ctx) =>
-    Effect.sync(() => {
-      console.error(`Execution failed: ${error}`);
-      ctx.updateState((s) => ({
-        ...s,
-        errorCount: s.errorCount + 1,
-        lastError: String(error),
-      }));
-    }),
-});
+```
+{jobType}:{jobName}:{userProvidedId}
 ```
 
-### Typed Errors
+For example: `continuous:tokenRefresher:user-123`
 
-Define typed errors for better error handling:
+### State Schemas
 
-```ts
-class RefreshError extends Data.TaggedError("RefreshError")<{
-  readonly reason: string;
-}> {}
+All jobs use Effect Schema for state validation and serialization:
 
-const typedPrimitive = Continuous.make({
-  stateSchema: Schema.Struct({ token: Schema.String }),
-  schedule: Continuous.every("1 hour"),
+```typescript
+const stateSchema = Schema.Struct({
+  // Basic types
+  count: Schema.Number,
+  name: Schema.String,
+  active: Schema.Boolean,
 
-  execute: (ctx) =>
-    Effect.gen(function* () {
-      const result = yield* refreshToken(ctx.state.token);
-      if (!result.ok) {
-        return yield* Effect.fail(new RefreshError({ reason: result.error }));
-      }
-      ctx.setState({ token: result.token });
-    }),
+  // Rich types (automatically encoded/decoded)
+  createdAt: Schema.DateFromSelf,
+  data: Schema.Unknown,
 
-  onError: (error, ctx) =>
-    Effect.sync(() => {
-      // error is typed as RefreshError
-      console.error(`Refresh failed: ${error.reason}`);
-    }),
+  // Optional fields
+  lastError: Schema.optional(Schema.String),
 });
 ```
 
-## Testing
+State is validated on read/write. Invalid state throws `ValidationError`.
 
-Use the test runtime for unit testing:
+### Terminate vs Stop
 
-```ts
-import { describe, it, expect } from "vitest";
-import { Effect, Schema } from "effect";
-import { createTestRuntime, NoopTrackerLayer } from "@durable-effect/core";
-import { createJobsRuntimeFromLayer } from "@durable-effect/jobs";
-
-describe("tokenRefresher", () => {
-  it("refreshes token on schedule", async () => {
-    // Create test runtime with time control
-    const { layer, time, handles } = createTestRuntime("test-instance", 1000000);
-
-    // Create registry (manually add name for test registry)
-    const registry = {
-      continuous: new Map([["tokenRefresher", { ...tokenRefresher, name: "tokenRefresher" }]]),
-      debounce: new Map(),
-      workerPool: new Map(),
-    };
-
-    // Create runtime from test layer
-    const runtime = createJobsRuntimeFromLayer(layer, registry);
-
-    // Start the primitive
-    await runtime.handle({
-      type: "continuous",
-      action: "start",
-      name: "tokenRefresher",
-      id: "test-user",
-      input: { accessToken: "", refreshToken: "rt_test", expiresAt: 0 },
-    });
-
-    // Advance time past schedule
-    time.advance(30 * 60 * 1000); // 30 minutes
-
-    // Trigger alarm
-    await runtime.handleAlarm();
-
-    // Verify state was updated
-    const result = await runtime.handle({
-      type: "continuous",
-      action: "getState",
-      name: "tokenRefresher",
-      id: "test-user",
-    });
-
-    expect(result.state.accessToken).toBeDefined();
-  });
-});
+- **`terminate()`**: Removes all state and cancels alarms. The instance ID can be reused to start fresh.
+- Jobs don't have a "pause" concept - they're either running or terminated.
+
+### Schedule Inputs
+
+Task's `schedule()` accepts flexible time inputs:
+
+```typescript
+// Duration (from now)
+yield* ctx.schedule(Duration.seconds(30));
+yield* ctx.schedule("5 minutes");
+
+// Absolute timestamp (ms since epoch)
+yield* ctx.schedule(Date.now() + 60000);
+
+// Date object
+yield* ctx.schedule(new Date("2024-12-31"));
 ```
 
-## Examples
+---
 
-### Daily Report Generator
+## Retry Configuration
 
-```ts
-const dailyReport = Continuous.make({
-  stateSchema: Schema.Struct({
-    lastReportDate: Schema.NullOr(Schema.String),
-    totalReports: Schema.Number,
-  }),
-  schedule: Continuous.every("24 hours"),
-  startImmediately: false, // Wait for first schedule
+Configure automatic retries for execute failures:
+
+```typescript
+import { Backoff } from "@durable-effect/core";
 
+const job = Continuous.make({
+  // ...
+  retry: {
+    maxAttempts: 3,
+    delay: Backoff.exponential({
+      base: "1 second",
+      max: "30 seconds",
+    }),
+    jitter: true,  // Add randomness to prevent thundering herd
+  },
   execute: (ctx) =>
     Effect.gen(function* () {
-      const report = yield* generateReport();
-      yield* sendReport(report);
-
-      ctx.updateState((s) => ({
-        lastReportDate: new Date().toISOString(),
-        totalReports: s.totalReports + 1,
-      }));
+      if (ctx.isRetry) {
+        console.log(`Retry attempt ${ctx.attempt}`);
+      }
+      // ... your logic
     }),
 });
 ```
 
-### Health Check Monitor
+**Retry behavior:**
+- Retries are scheduled via alarms (durable, survives restarts)
+- When all retries exhausted, the job is terminated (state purged)
+- A `job.retryExhausted` event is emitted for observability
 
-```ts
-const healthCheck = Continuous.make({
-  stateSchema: Schema.Struct({
-    status: Schema.Literal("healthy", "degraded", "down"),
-    lastCheck: Schema.Number,
-    consecutiveFailures: Schema.Number,
-  }),
-  schedule: Continuous.every("1 minute"),
+**Backoff strategies:**
 
-  execute: (ctx) =>
-    Effect.gen(function* () {
-      const isHealthy = yield* checkHealth();
+```typescript
+// Exponential: 1s, 2s, 4s, 8s... (capped at max)
+Backoff.exponential({ base: "1 second", max: "30 seconds" })
 
-      ctx.updateState((s) => ({
-        status: isHealthy ? "healthy" : s.consecutiveFailures >= 3 ? "down" : "degraded",
-        lastCheck: Date.now(),
-        consecutiveFailures: isHealthy ? 0 : s.consecutiveFailures + 1,
-      }));
+// Linear: 1s, 2s, 3s, 4s...
+Backoff.linear({ base: "1 second", increment: "1 second" })
 
-      if (!isHealthy && ctx.state.consecutiveFailures >= 3) {
-        yield* sendAlert("Service is down!");
-      }
-    }),
-});
+// Fixed: always 5s
+Backoff.fixed("5 seconds")
 ```
 
-### Cache Warmer
+---
 
-```ts
-const cacheWarmer = Continuous.make({
-  stateSchema: Schema.Struct({
-    lastWarmTime: Schema.Number,
-    itemsWarmed: Schema.Number,
-  }),
-  schedule: Continuous.every("15 minutes"),
+## Logging
 
-  execute: (ctx) =>
-    Effect.gen(function* () {
-      const items = yield* getPopularItems();
+Control logging per job:
 
-      for (const item of items) {
-        yield* warmCache(item);
-      }
+```typescript
+import { LogLevel } from "effect";
 
-      ctx.setState({
-        lastWarmTime: Date.now(),
-        itemsWarmed: items.length,
-      });
-    }),
+const job = Continuous.make({
+  // ...
+  logging: true,           // LogLevel.Debug (all logs)
+  logging: false,          // LogLevel.Error (failures only) - DEFAULT
+  logging: LogLevel.Warning,
+  logging: LogLevel.None,  // Silent
 });
 ```
 
-## Architecture
+---
 
-The Continuous primitive is built on a thin Durable Object shell that delegates to a swappable runtime:
+## Telemetry
 
+Send job events to an external endpoint:
+
+```typescript
+const { Jobs, JobsClient } = createDurableJobs(
+  { tokenRefresher, webhookBatcher },
+  {
+    tracker: {
+      endpoint: "https://events.example.com/ingest",
+      env: "production",
+      serviceKey: "my-jobs-service",
+    },
+  }
+);
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                     Worker Code                              │
-│  client.continuous("name").start({ id, input })             │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│              Durable Object (Thin Shell)                     │
-│                                                              │
-│  • Receives RPC calls                                        │
-│  • Delegates to JobsRuntime                           │
-│  • Handles alarms                                            │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   Jobs Runtime                         │
-│                                                              │
-│  • Routes requests to handlers                               │
-│  • Manages state via StorageAdapter                         │
-│  • Schedules alarms via SchedulerAdapter                    │
-│  • Executes user functions                                   │
-└─────────────────────────────────────────────────────────────┘
+
+**Emitted events:**
+- `job.started` - Job instance created
+- `job.executed` - Execute completed successfully
+- `job.failed` - Execute threw an error
+- `job.retryExhausted` - All retries failed
+- `job.terminated` - Job instance terminated
+- `debounce.started` - First event added
+- `debounce.flushed` - Batch processed
+- `task.scheduled` - Execution scheduled
+
+---
+
+## Error Types
+
+All errors are typed Effect errors:
+
+```typescript
+import {
+  JobNotFoundError,      // Job name not in registry
+  InstanceNotFoundError, // Instance has no metadata
+  InvalidStateError,     // Invalid state transition
+  ValidationError,       // Schema validation failed
+  ExecutionError,        // User function threw
+  DuplicateEventError,   // Idempotency check failed
+  StorageError,          // Durable Object storage error
+  SchedulerError,        // Alarm scheduling error
+} from "@durable-effect/jobs";
 ```
 
-Each instance has its own:
-- **Storage** - Isolated key-value storage for state
-- **Alarm** - Single alarm for scheduling next execution
-- **Instance ID** - Format: `continuous:{name}:{userProvidedId}`
+---
 
-## License
+## Effect Service Integration
 
-MIT
+TODO