@structure-ai/jobs 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ligerian Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @structure-ai/jobs
+
+Delayed and recurring jobs on PostgreSQL. Jobs are named, schema-typed handlers registered at boot; the queue is a pair of tables dispatched with `SELECT … FOR UPDATE SKIP LOCKED`, heartbeat leases, at-least-once delivery, bounded jittered retries, and dead letters. Workers drain gracefully through the `@structure-ai/runtime` Shutdown coordinator, and every execution carries the scheduling site's correlation id.
+
+## Quick start
+
+```ts
+import { defineJob, jobsReadinessCheck, layer, workerLayer, Scheduler } from "@structure-ai/jobs";
+import { Effect, Layer, Schema } from "effect";
+
+const SendDigest = defineJob(
+  {
+    name: "digest.send",
+    payloadSchema: Schema.parseJson(Schema.Struct({ userId: Schema.String })),
+  },
+  (payload) => sendDigest(payload.userId),
+  { maxAttempts: 5 },
+);
+
+const Jobs = layer({ url: process.env.DATABASE_URL });      // PgClient + migrate + Scheduler
+const Worker = workerLayer({ role: "all" });                // drains on shutdown
+
+// Scheduling (from commands, HTTP handlers, anywhere):
+//   yield* scheduler.schedule(SendDigest, { userId }, { delay: "5 minutes" });
+//   yield* scheduler.recur(SendDigest, { userId }, { cron: "0 9 * * mon-fri", timezone: "Europe/Paris" });
+```
+
+## Handlers, scheduling, cancellation
+
+```ts
+const scheduler = yield* Scheduler;
+
+yield* scheduler.register(SendDigest);          // named handlers, idempotent per name
+const id = yield* scheduler.schedule(SendDigest, { userId: "u-1" }, { delay: "1 hour" });
+yield* scheduler.recur(SendDigest, { userId: "u-1" }, {
+  cron: "*/5 * * * *",        // 5-field cron: lists, ranges, steps, day names
+  timezone: "UTC",            // IANA names, DST-aware
+  scheduleKey: "digest-u-1",  // one row per key; recur replaces it
+});
+yield* scheduler.cancel(id);
+```
+
+Payloads are `Schema<P, string>` (usually `Schema.parseJson(...)`) — stored as text, decoded before each execution; a payload that no longer decodes dead-letters immediately.
+
+## Delivery semantics
+
+- **At-least-once.** Handlers must be idempotent or dedupe (e.g. through `@structure-ai/eventsourcing`'s Inbox). A lease that expires (worker crash, GC pause) makes the run reclaimable — the job may execute twice.
+- **Retries.** Handlers fail with `{ reason, classification }`: `transient` failures retry with exponential jittered backoff (1s base, 5min cap) up to `maxAttempts` (default 5); `permanent` failures dead-letter on the spot.
+- **Dead letters.** Exhausted or permanently failed jobs move to `jobs_dead_letters` with their attempts, last error (bounded), and correlation id — inspectable with plain SQL.
+- **Cron missed-run policy: skip.** The next occurrence is computed strictly after `max(scheduled, now)` — downtime never produces a catch-up burst.
+- **`JobContext.atLeastOnce: true`** is carried into every execution as standing guidance.
+
+## Worker lifecycle and roles
+
+`workerLayer({ role })` follows the platform's `SERVICE_ROLE` convention: `api` processes only schedule (the layer logs and does nothing), `worker`/`all` fork the dispatch loop. The loop registers a `Shutdown` finalizer: on shutdown it stops claiming, waits for in-flight handlers (bounded by the coordinator's finalizer timeout), then exits — no in-flight job is killed. `jobsSettings` (`@structure-ai/config`) maps `SERVICE_ROLE`, `JOBS_POLL_INTERVAL`, `JOBS_BATCH_SIZE`, `JOBS_LEASE`, `JOBS_TABLE_PREFIX`.
+
+## Observability
+
+Per-job metrics under bounded, handler-derived names: `job_<name>_calls_total` / `_errors_total` / `_duration_ms` (via `Metrics.track`), plus `jobs_dispatched_total`, `jobs_succeeded_total`, `jobs_retried_total`, `jobs_dead_lettered_total` and the `jobs_queue_depth` gauge. Structured logs per scheduling and per attempt carry job id, name, attempt, classification, bounded reason, and the correlation id captured at the scheduling site (`Correlation.within` at dispatch). `jobsReadinessCheck(scheduler, { maxDepth, maxLagMillis })` reports queue depth/lag into `/health/ready`.
+
+## Errors
+
+`UnknownJob`, `InvalidJobPayload` (permanent), `JobQueueError` (transient), `InvalidCronExpression` (permanent, lists every problem). All classified per the framework taxonomy.
+
+## Schema
+
+Two tables created by the idempotent `migrate` (own prefix, `@structure-ai/migrations`-compatible DDL): `jobs_queue` (status `queued|running`, `run_at`, `cron_expr`, `cron_timezone`, `attempt`, `max_attempts`, `lease_expires_at`, `last_error`, correlation fields) with dispatch and lease indexes, and `jobs_dead_letters`.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@structure-ai/jobs",
+  "version": "0.0.10",
+  "description": "Delayed and recurring jobs on PostgreSQL: named schema-typed handlers, SKIP LOCKED dispatch with heartbeat leases, cron scheduling with timezones, at-least-once delivery, dead letters, graceful drain, per-job metrics.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ligerian-labs/structure.git",
+    "directory": "packages/jobs"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@structure-ai/config": "0.0.10",
+    "@structure-ai/observability": "0.0.10",
+    "@structure-ai/runtime": "0.0.10",
+    "@effect/sql": "^0.52.1",
+    "@effect/sql-pg": "^0.53.0",
+    "effect": "^3.22.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.2"
+  }
+}

package/src/cron.ts

@@ -0,0 +1,295 @@
+import { Data, Effect } from "effect";
+
+/** A cron expression is invalid (unknown field, out of range, bad syntax). */
+export class InvalidCronExpression extends Data.TaggedError("InvalidCronExpression")<{
+  readonly expression: string;
+  readonly problems: ReadonlyArray<string>;
+}> {
+  readonly classification: "permanent" = "permanent";
+  override get message(): string {
+    return `invalid cron expression "${this.expression}": ${this.problems.join("; ")}`;
+  }
+}
+
+/** A 5-field cron schedule: minute hour day-of-month month day-of-week. */
+export interface CronFields {
+  readonly minutes: ReadonlyArray<number>;
+  readonly hours: ReadonlyArray<number>;
+  readonly daysOfMonth: ReadonlyArray<number>;
+  readonly months: ReadonlyArray<number>;
+  readonly daysOfWeek: ReadonlyArray<number>;
+  /** `true` when day-of-month is unrestricted (`*`) — matters when dow is restricted. */
+  readonly domRestricted: boolean;
+  readonly dowRestricted: boolean;
+}
+
+const RANGES: ReadonlyArray<[string, number, number]> = [
+  ["minute", 0, 59],
+  ["hour", 0, 23],
+  ["day-of-month", 1, 31],
+  ["month", 1, 12],
+  ["day-of-week", 0, 6],
+];
+
+const DAY_NAMES: Readonly<Record<string, number>> = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6,
+};
+
+const parseField = (
+  field: string,
+  name: string,
+  min: number,
+  max: number,
+): Effect.Effect<ReadonlyArray<number>, string> =>
+  Effect.gen(function* () {
+    const values = new Set<number>();
+    for (const part of field.split(",")) {
+      const stepMatch = /^(\*|\d+-\d+|\d+)(?:\/(\d+))?$/u.exec(part.trim());
+      if (stepMatch === null) {
+        return yield* Effect.fail(`${name}: cannot parse "${part}"`);
+      }
+      const rangePart = stepMatch[1] ?? "";
+      const step = stepMatch[2] === undefined ? 1 : Number(stepMatch[2]);
+      if (!Number.isInteger(step) || step < 1) {
+        return yield* Effect.fail(`${name}: step must be a positive integer`);
+      }
+      let from = min;
+      let to = max;
+      if (rangePart !== "*") {
+        if (rangePart.includes("-")) {
+          const [rawFrom, rawTo] = rangePart.split("-");
+          from = Number(rawFrom);
+          to = Number(rawTo);
+        } else {
+          from = Number(rangePart);
+          to = rangePart.includes("/") ? max : from;
+        }
+      }
+      if (!Number.isInteger(from) || !Number.isInteger(to) || from < min || to > max || from > to) {
+        return yield* Effect.fail(`${name}: values must be within ${min}-${max}`);
+      }
+      for (let value = from; value <= to; value += step) values.add(value);
+    }
+    return [...values].sort((a, b) => a - b);
+  });
+
+/**
+ * Parses a standard 5-field cron expression: `*`, lists (`1,15`), ranges
+ * (`1-5`), steps (every-10th `0/10`, range-stepped `5-40/5`). Day-of-week:
+ * 0 and 7 are Sunday.
+ */
+export const parseCron = (expression: string): Effect.Effect<CronFields, InvalidCronExpression> =>
+  Effect.gen(function* () {
+    const parts = expression.trim().split(/\s+/u);
+    if (parts.length !== 5) {
+      return yield* new InvalidCronExpression({
+        expression,
+        problems: [
+          `expected 5 fields (minute hour day-of-month month day-of-week), got ${parts.length}`,
+        ],
+      });
+    }
+    const problems: Array<string> = [];
+    const parsed: Array<ReadonlyArray<number>> = [];
+    for (let index = 0; index < parts.length; index++) {
+      const [name, min, max] = RANGES[index] ?? ["field", 0, 0];
+      const part = parts[index] ?? "*";
+      const field = part
+        .replace(/^7$/u, "0")
+        .replace(/\b(sun|mon|tue|wed|thu|fri|sat)\b/giu, (name) =>
+          String(DAY_NAMES[name.toLowerCase()] ?? name),
+        );
+      const result = yield* parseField(field, name, min, max).pipe(Effect.either);
+      if (result._tag === "Left") {
+        problems.push(result.left);
+        parsed.push([]);
+      } else {
+        parsed.push(result.right);
+      }
+    }
+    if (problems.length > 0) {
+      return yield* new InvalidCronExpression({ expression, problems });
+    }
+    const [minutes, hours, daysOfMonth, months, daysOfWeek] = parsed as [
+      ReadonlyArray<number>,
+      ReadonlyArray<number>,
+      ReadonlyArray<number>,
+      ReadonlyArray<number>,
+      ReadonlyArray<number>,
+    ];
+    return {
+      minutes,
+      hours,
+      daysOfMonth,
+      months,
+      daysOfWeek,
+      domRestricted: daysOfMonth.length !== 31,
+      dowRestricted: daysOfWeek.length !== 7,
+    };
+  });
+
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"] as const;
+
+/** Human-readable summary, e.g. `at 09:30 every mon-fri`. */
+export const describeCron = (fields: CronFields): string => {
+  const time =
+    fields.hours.length === 24 && fields.minutes.length === 60
+      ? "every minute"
+      : fields.hours
+          .flatMap((hour) =>
+            fields.minutes.map(
+              (minute) => `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`,
+            ),
+          )
+          .join(", ");
+  const days = fields.dowRestricted
+    ? fields.daysOfWeek.map((day) => DAYS[day] ?? String(day)).join(", ")
+    : "every day";
+  const months = fields.months.length === 12 ? "" : ` in months ${fields.months.join(",")}`;
+  const dom = fields.domRestricted ? ` on days ${fields.daysOfMonth.join(",")}` : "";
+  return `at ${time} ${days}${dom}${months}`;
+};
+
+interface WallClock {
+  readonly year: number;
+  readonly month: number; // 1-12
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly weekday: number; // 0=Sunday
+}
+
+const wallClockFormatter = (timeZone: string): Intl.DateTimeFormat => {
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hour12: false,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      weekday: "short",
+    });
+  } catch {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: "UTC",
+      hour12: false,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      weekday: "short",
+    });
+  }
+};
+
+const weekdayIndex: Readonly<Record<string, number>> = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+};
+
+const wallClockOf = (instant: Date, formatter: Intl.DateTimeFormat): WallClock => {
+  const parts = formatter.formatToParts(instant);
+  const pick = (type: string): number => {
+    const value = parts.find((part) => part.type === type)?.value ?? "0";
+    return Number(value);
+  };
+  const weekday = weekdayIndex[parts.find((part) => part.type === "weekday")?.value ?? "Sun"] ?? 0;
+  const hour = pick("hour") % 24;
+  return {
+    year: pick("year"),
+    month: pick("month"),
+    day: pick("day"),
+    hour,
+    minute: pick("minute"),
+    weekday,
+  };
+};
+
+/** UTC instant for a wall-clock time in `timeZone` (two-pass DST offset). */
+const instantFromWallClock = (
+  clock: Omit<WallClock, "weekday">,
+  formatter: Intl.DateTimeFormat,
+): Date => {
+  const guess = Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, 0, 0);
+  const wallAtGuess = wallClockOf(new Date(guess), formatter);
+  const wallAsUtc = Date.UTC(
+    wallAtGuess.year,
+    wallAtGuess.month - 1,
+    wallAtGuess.day,
+    wallAtGuess.hour,
+    wallAtGuess.minute,
+    0,
+    0,
+  );
+  const offset = wallAsUtc - guess;
+  return new Date(guess - offset);
+};
+
+const dayMatches = (clock: WallClock, fields: CronFields): boolean => {
+  if (!fields.months.includes(clock.month)) return false;
+  const domOk = fields.daysOfMonth.includes(clock.day);
+  const dowOk = fields.daysOfWeek.includes(clock.weekday);
+  // POSIX cron: when both dom and dow are restricted, either may match.
+  if (fields.domRestricted && fields.dowRestricted) return domOk || dowOk;
+  if (fields.domRestricted) return domOk;
+  if (fields.dowRestricted) return dowOk;
+  return true;
+};
+
+const SEARCH_LIMIT_DAYS = 400;
+
+/**
+ * The next fire time strictly after `after`, in the expression's timezone
+ * (default UTC). Missed occurrences are skipped — the scheduler never
+ * bursts to catch up on time that already passed while it was down.
+ */
+export const nextRun = (after: Date, fields: CronFields, timeZone = "UTC"): Date | undefined => {
+  const formatter = wallClockFormatter(timeZone);
+  const start = wallClockOf(after, formatter);
+  for (let dayOffset = 0; dayOffset <= SEARCH_LIMIT_DAYS; dayOffset++) {
+    // Walk whole days: from the minute after `after` on day 0, then full days.
+    const base = instantFromWallClock(
+      {
+        year: start.year,
+        month: start.month,
+        day: start.day,
+        hour: 0,
+        minute: 0,
+      },
+      formatter,
+    );
+    const dayStart = new Date(base.getTime() + dayOffset * 86_400_000);
+    const dayClock = wallClockOf(dayStart, formatter);
+    if (!dayMatches(dayClock, fields)) continue;
+    for (const hour of fields.hours) {
+      for (const minute of fields.minutes) {
+        const candidate = instantFromWallClock(
+          {
+            year: dayClock.year,
+            month: dayClock.month,
+            day: dayClock.day,
+            hour,
+            minute,
+          },
+          formatter,
+        );
+        if (candidate.getTime() > after.getTime()) return candidate;
+      }
+    }
+  }
+  return undefined;
+};

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * `@structure-ai/jobs` — delayed and recurring jobs on PostgreSQL: named
+ * schema-typed handlers, SKIP LOCKED dispatch with heartbeat leases, cron
+ * scheduling with timezone support, at-least-once delivery, bounded jittered
+ * retries with dead letters, graceful drain through the Shutdown
+ * coordinator, per-job metrics and correlation propagation.
+ */
+
+export {
+  type CronFields,
+  describeCron,
+  InvalidCronExpression,
+  nextRun,
+  parseCron,
+} from "./cron.js";
+export { type JobsLayerOptions, layer, workerLayer } from "./layer.js";
+export { type JobsReadinessOptions, jobsReadinessCheck } from "./readiness.js";
+export {
+  backoffMillis,
+  defineJob,
+  InvalidJobPayload,
+  type JobContext,
+  type JobFailure,
+  type JobHandler,
+  type JobId,
+  JobQueueError,
+  type JobRef,
+  jobFailure,
+  makeScheduler,
+  type RecurOptions,
+  type ScheduleOptions,
+  Scheduler,
+  type SchedulerOptions,
+  type SchedulerService,
+  schedulerLayer,
+  UnknownJob,
+  type WorkerOptions,
+} from "./scheduler.js";
+export { type AdapterOptions, migrate, type TableNames, tableNames } from "./schema.js";
+export { jobsSettings } from "./settings.js";

package/src/layer.ts

@@ -0,0 +1,69 @@
+import type * as SqlClient from "@effect/sql/SqlClient";
+import type { SqlError } from "@effect/sql/SqlError";
+import { PgClient } from "@effect/sql-pg";
+import type { Shutdown } from "@structure-ai/runtime";
+import { Effect, Layer, Redacted } from "effect";
+import {
+  Scheduler,
+  type SchedulerOptions,
+  schedulerLayer,
+  type WorkerOptions,
+} from "./scheduler.js";
+import { migrate } from "./schema.js";
+
+/** All-in-one layer configuration. */
+export interface JobsLayerOptions extends SchedulerOptions {
+  /**
+   * Postgres connection URL. Defaults to `DATABASE_URL`; when neither is
+   * set, the client falls back to libpq defaults.
+   */
+  readonly url?: string;
+  readonly maxConnections?: number;
+  readonly applicationName?: string;
+}
+
+/**
+ * Everything in one layer: a `PgClient` (from `options.url` or
+ * `DATABASE_URL`), the schema migration at build, and the `Scheduler`
+ * service. The client is exposed for the app's own queries.
+ */
+export const layer = (
+  options?: JobsLayerOptions,
+): Layer.Layer<Scheduler | PgClient.PgClient | SqlClient.SqlClient, SqlError> => {
+  const url = options?.url ?? process.env.DATABASE_URL;
+  const client = PgClient.layer({
+    ...(url !== undefined ? { url: Redacted.make(url) } : {}),
+    ...(options?.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
+    ...(options?.applicationName !== undefined ? { applicationName: options.applicationName } : {}),
+  });
+  const migrated = Layer.effectDiscard(migrate(options)).pipe(Layer.provideMerge(client));
+  return schedulerLayer(options).pipe(Layer.provideMerge(migrated));
+};
+
+/**
+ * Worker layer: role-aware boot. `api` starts nothing (the process only
+ * schedules); `worker` and `all` fork the dispatch loop inside a scope and
+ * register a `Shutdown` finalizer that drains it — no in-flight job is
+ * killed on shutdown. Compose on top of {@link layer}.
+ *
+ * ```ts
+ * const Jobs = layer({ url: process.env.DATABASE_URL });
+ * const Worker = workerLayer({ role: process.env.SERVICE_ROLE as "api" });
+ * // Layer.provide(Worker, Jobs) — or merge both into the runtime.
+ * ```
+ */
+export const workerLayer = (
+  options?: WorkerOptions,
+): Layer.Layer<never, never, Scheduler | Shutdown> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const scheduler = yield* Scheduler;
+      if ((options?.role ?? "all") === "api") {
+        yield* Effect.logInfo("jobs worker not started (api role)").pipe(
+          Effect.annotateLogs({ jobsRole: "api" }),
+        );
+        return;
+      }
+      yield* Effect.forkScoped(scheduler.runWorker(options));
+    }),
+  );

package/src/readiness.ts

@@ -0,0 +1,30 @@
+import type { ReadinessCheck } from "@structure-ai/runtime";
+import { Effect } from "effect";
+import type { SchedulerService } from "./scheduler.js";
+
+export interface JobsReadinessOptions {
+  /** Ready fails when the queue holds more than this many jobs. */
+  readonly maxDepth?: number;
+  /** Ready fails when the oldest due job has waited longer than this. */
+  readonly maxLagMillis?: number;
+}
+
+/**
+ * Readiness check reporting queue health: depth and lag of due work. A
+ * process whose scheduler cannot keep up (or whose queue is unreachable)
+ * reports not-ready so orchestrators stop routing to it. Defaults are
+ * generous: 10_000 depth, 5 minutes of lag.
+ */
+export const jobsReadinessCheck = (
+  scheduler: SchedulerService,
+  options: JobsReadinessOptions = {},
+): ReadinessCheck => ({
+  name: "jobs",
+  run: Effect.gen(function* () {
+    const depth = yield* scheduler.depth.pipe(Effect.orElseSucceed(() => Number.POSITIVE_INFINITY));
+    const lag = yield* scheduler.lagMillis.pipe(
+      Effect.orElseSucceed(() => Number.POSITIVE_INFINITY),
+    );
+    return depth <= (options.maxDepth ?? 10_000) && lag <= (options.maxLagMillis ?? 5 * 60_000);
+  }),
+});

package/src/scheduler.ts

@@ -0,0 +1,616 @@
+import * as SqlClient from "@effect/sql/SqlClient";
+import { Correlation, Metrics } from "@structure-ai/observability";
+import { Shutdown } from "@structure-ai/runtime";
+import {
+  Context,
+  Data,
+  Duration,
+  Effect,
+  Fiber,
+  Layer,
+  Metric,
+  Schema as S,
+  Schedule,
+} from "effect";
+import { InvalidCronExpression, nextRun, parseCron } from "./cron.js";
+import { type AdapterOptions, tableNames } from "./schema.js";
+
+// --- errors ---------------------------------------------------------------------
+
+/** The job reference is not registered in this process. */
+export class UnknownJob extends Data.TaggedError("UnknownJob")<{
+  readonly jobName: string;
+}> {
+  readonly classification: "permanent" = "permanent";
+  override get message(): string {
+    return `job "${this.jobName}" is not registered`;
+  }
+}
+
+/** The payload failed schema decoding. */
+export class InvalidJobPayload extends Data.TaggedError("InvalidJobPayload")<{
+  readonly jobName: string;
+  readonly reason: string;
+}> {
+  readonly classification: "permanent" = "permanent";
+  override get message(): string {
+    return `payload for job "${this.jobName}" is invalid`;
+  }
+}
+
+/** Scheduling failed against the queue. Transient. */
+export class JobQueueError extends Data.TaggedError("JobQueueError")<{
+  readonly operation: string;
+  readonly cause?: unknown;
+}> {
+  readonly classification: "transient" = "transient";
+  override get message(): string {
+    return `job queue failed during ${this.operation}`;
+  }
+}
+
+/** Storage shape a handler returns to steer retry behavior. */
+export interface JobFailure {
+  readonly reason: string;
+  readonly classification: "transient" | "permanent";
+}
+
+// --- definitions ------------------------------------------------------------------
+
+/** Minimal reference for scheduling: a name plus its payload codec schema. */
+export interface JobRef<P> {
+  readonly name: string;
+  /** Schema between the payload type and its stored JSON text. */
+  readonly payloadSchema: S.Schema<P, string>;
+}
+
+export interface JobContext {
+  readonly jobId: string;
+  readonly attempt: number;
+  readonly scheduledFor: Date;
+  /** Delivery is at-least-once: handlers must be idempotent or dedupe. */
+  readonly atLeastOnce: true;
+}
+
+/** A named handler registered at boot; the scheduler dispatches into it. */
+export interface JobHandler<P> extends JobRef<P> {
+  readonly handle: (payload: P, context: JobContext) => Effect.Effect<void, JobFailure>;
+  /** Overrides the default of 5 attempts (transient failures only). */
+  readonly maxAttempts?: number;
+}
+
+/** Type-erased handler as the scheduler stores it internally. */
+export interface StoredJobHandler {
+  readonly name: string;
+  readonly payloadSchema: S.Schema<unknown, string>;
+  readonly handle: (payload: unknown, context: JobContext) => Effect.Effect<void, JobFailure>;
+  readonly maxAttempts?: number;
+}
+
+export const defineJob = <P>(
+  ref: JobRef<P>,
+  handle: JobHandler<P>["handle"],
+  options?: { readonly maxAttempts?: number },
+): JobHandler<P> => ({
+  ...ref,
+  handle,
+  ...(options?.maxAttempts === undefined ? {} : { maxAttempts: options.maxAttempts }),
+});
+
+// --- scheduler service --------------------------------------------------------------
+
+export type JobId = string;
+
+export interface ScheduleOptions {
+  /** Delay before the job becomes due. Default: immediately. */
+  readonly delay?: Duration.DurationInput;
+  /** Overrides the scheduling site's correlation id. */
+  readonly correlationId?: string;
+}
+
+export interface RecurOptions {
+  /** 5-field cron expression, evaluated in `timezone` (default UTC). */
+  readonly cron: string;
+  readonly timezone?: string;
+  /**
+   * Stable id for the recurring row: one row per key, `recur` replaces it.
+   * Defaults to a fresh uuid (a second call schedules a second row).
+   */
+  readonly scheduleKey?: string;
+  readonly correlationId?: string;
+}
+
+export interface WorkerOptions {
+  /** Idle poll interval. Default 1s. */
+  readonly pollInterval?: Duration.DurationInput;
+  /** Claims per poll. Default 10. */
+  readonly batchSize?: number;
+  /** Lease held while a handler runs; expiry makes the row reclaimable. Default 60s. */
+  readonly lease?: Duration.DurationInput;
+  /**
+   * Role-aware boot: `api` runs no worker (scheduling only), `worker` and
+   * `all` do. Default `all`.
+   */
+  readonly role?: "api" | "worker" | "all";
+}
+
+interface QueueRow {
+  readonly id: string;
+  readonly job_name: string;
+  readonly payload: string;
+  readonly attempt: number;
+  readonly max_attempts: number;
+  readonly cron_expr: string | null;
+  readonly cron_timezone: string | null;
+  readonly correlation_id: string | null;
+  readonly run_at: Date | string;
+}
+
+export interface SchedulerService {
+  /** Registers a named handler. Idempotent per name (last registration wins). */
+  readonly register: <P>(handler: JobHandler<P>) => Effect.Effect<void>;
+  readonly schedule: <P>(
+    job: JobRef<P>,
+    payload: P,
+    options?: ScheduleOptions,
+  ) => Effect.Effect<JobId, InvalidJobPayload | JobQueueError>;
+  readonly recur: <P>(
+    job: JobRef<P>,
+    payload: P,
+    options: RecurOptions,
+  ) => Effect.Effect<JobId, InvalidCronExpression | InvalidJobPayload | JobQueueError>;
+  readonly cancel: (jobId: JobId) => Effect.Effect<void, JobQueueError>;
+  /** Queue depth: rows not yet completed (queued + running). */
+  readonly depth: Effect.Effect<number, JobQueueError>;
+  /** Lag: milliseconds since the oldest due-but-incomplete run. */
+  readonly lagMillis: Effect.Effect<number, JobQueueError>;
+  /** Names of registered handlers, for boot-time wiring checks. */
+  readonly registeredJobs: () => ReadonlyArray<string>;
+  /**
+   * Runs the worker loop until the Shutdown coordinator triggers, then
+   * drains: no in-flight job is interrupted. Claims with
+   * `FOR UPDATE SKIP LOCKED`, heartbeats its lease, retries transient
+   * failures with jittered backoff, and dead-letters permanent failures and
+   * exhausted attempts.
+   */
+  readonly runWorker: (options?: WorkerOptions) => Effect.Effect<void, never, Shutdown>;
+}
+
+export class Scheduler extends Context.Tag("@structure-ai/jobs/Scheduler")<
+  Scheduler,
+  SchedulerService
+>() {}
+
+export interface SchedulerOptions extends AdapterOptions {
+  /** Injectable clock for deterministic tests. */
+  readonly now?: () => Date;
+  readonly random?: () => number;
+}
+
+const runAtOf = (row: QueueRow): Date =>
+  row.run_at instanceof Date ? row.run_at : new Date(row.run_at);
+
+/** Backoff for attempt N (1-based): exponential, capped, ±50% jitter. */
+export const backoffMillis = (
+  attempt: number,
+  random: () => number,
+  baseMillis = 1_000,
+  capMillis = 5 * 60_000,
+): number => {
+  const exponential = Math.min(baseMillis * 2 ** (attempt - 1), capMillis);
+  return Math.round(exponential * (0.5 + random()));
+};
+
+export const makeScheduler = (
+  options: SchedulerOptions = {},
+): Effect.Effect<SchedulerService, never, SqlClient.SqlClient> =>
+  Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const tables = tableNames(options);
+    const now = options.now ?? (() => new Date());
+    const random = options.random ?? Math.random;
+    const handlers = new Map<string, StoredJobHandler>();
+
+    const dispatched = Metric.counter("jobs_dispatched_total", { incremental: true });
+    const succeeded = Metric.counter("jobs_succeeded_total", { incremental: true });
+    const retried = Metric.counter("jobs_retried_total", { incremental: true });
+    const deadLettered = Metric.counter("jobs_dead_lettered_total", { incremental: true });
+    const boundaries = new Map<string, Metrics.BoundaryMetrics>();
+    const boundaryFor = (jobName: string): Metrics.BoundaryMetrics => {
+      const existing = boundaries.get(jobName);
+      if (existing !== undefined) return existing;
+      const created = Metrics.boundary(`job_${jobName}`);
+      boundaries.set(jobName, created);
+      return created;
+    };
+
+    const queueError = (operation: string, cause: unknown): JobQueueError =>
+      new JobQueueError({ operation, cause });
+
+    const encodePayload = <P>(schema: S.Schema<P, string>, payload: P) =>
+      S.encodeUnknown(schema)(payload);
+
+    const maxAttemptsFor = (jobName: string): number => handlers.get(jobName)?.maxAttempts ?? 5;
+
+    const deadLetter = (row: QueueRow, reason: string): Effect.Effect<void, JobQueueError> =>
+      Effect.gen(function* () {
+        yield* sql`
+          INSERT INTO ${sql(tables.deadLetters)}
+            (id, job_name, payload, attempts, last_error, correlation_id, dead_at)
+          VALUES
+            (${crypto.randomUUID()}, ${row.job_name}, ${row.payload}, ${row.attempt},
+             ${reason.slice(0, 2_048)}, ${row.correlation_id}, ${now().toISOString()})
+        `;
+        yield* sql`DELETE FROM ${sql(tables.queue)} WHERE id = ${row.id}`;
+        yield* Metric.increment(deadLettered);
+        yield* Effect.logError("job dead-lettered").pipe(
+          Effect.annotateLogs({
+            jobId: row.id,
+            jobName: row.job_name,
+            jobAttempts: row.attempt,
+            jobReason: reason.slice(0, 256),
+          }),
+        );
+      }).pipe(Effect.mapError((cause) => queueError("dead-letter", cause)));
+
+    const completeSuccess = (row: QueueRow): Effect.Effect<void, JobQueueError> =>
+      Effect.gen(function* () {
+        if (row.cron_expr === null) {
+          yield* sql`DELETE FROM ${sql(tables.queue)} WHERE id = ${row.id}`;
+          return;
+        }
+        const fields = yield* parseCron(row.cron_expr);
+        const timezone = row.cron_timezone ?? "UTC";
+        // Missed-run policy: skip. The next fire is strictly after
+        // max(scheduled time, now) — downtime never produces a catch-up burst.
+        const next = nextRun(
+          new Date(Math.max(runAtOf(row).getTime(), now().getTime())),
+          fields,
+          timezone,
+        );
+        if (next === undefined) {
+          yield* sql`DELETE FROM ${sql(tables.queue)} WHERE id = ${row.id}`;
+          return;
+        }
+        yield* sql`
+          UPDATE ${sql(tables.queue)}
+          SET status = 'queued', run_at = ${next.toISOString()}, attempt = 0,
+              lease_expires_at = NULL, updated_at = ${now().toISOString()}
+          WHERE id = ${row.id}
+        `;
+      }).pipe(Effect.mapError((cause) => queueError("complete-success", cause)));
+
+    const rescheduleRetry = (row: QueueRow, reason: string): Effect.Effect<void, JobQueueError> =>
+      Effect.gen(function* () {
+        const backoff = backoffMillis(row.attempt, random);
+        yield* sql`
+          UPDATE ${sql(tables.queue)}
+          SET status = 'queued', run_at = ${new Date(now().getTime() + backoff).toISOString()},
+              lease_expires_at = NULL, last_error = ${reason.slice(0, 2_048)},
+              updated_at = ${now().toISOString()}
+          WHERE id = ${row.id}
+        `;
+        yield* Metric.increment(retried);
+        yield* Effect.logWarning("job attempt failed, retrying with backoff").pipe(
+          Effect.annotateLogs({
+            jobId: row.id,
+            jobName: row.job_name,
+            jobAttempt: row.attempt,
+            jobBackoffMillis: backoff,
+            jobReason: reason.slice(0, 256),
+          }),
+        );
+      }).pipe(Effect.mapError((cause) => queueError("reschedule-retry", cause)));
+
+    const claim = (
+      batchSize: number,
+      leaseMillis: number,
+    ): Effect.Effect<ReadonlyArray<QueueRow>, JobQueueError> => {
+      const timestamp = now();
+      const leaseUntil = new Date(timestamp.getTime() + leaseMillis);
+      return sql<QueueRow>`
+        WITH picked AS (
+          SELECT id FROM ${sql(tables.queue)}
+          WHERE (status = 'queued' AND run_at <= ${timestamp.toISOString()})
+             OR (status = 'running' AND lease_expires_at <= ${timestamp.toISOString()})
+          ORDER BY run_at
+          LIMIT ${batchSize}
+          FOR UPDATE SKIP LOCKED
+        )
+        UPDATE ${sql(tables.queue)} queue
+        SET status = 'running', attempt = queue.attempt + 1,
+            lease_expires_at = ${leaseUntil.toISOString()},
+            updated_at = ${timestamp.toISOString()}
+        FROM picked
+        WHERE queue.id = picked.id
+        RETURNING queue.id, queue.job_name, queue.payload, queue.attempt,
+                  queue.max_attempts, queue.cron_expr, queue.cron_timezone,
+                  queue.correlation_id, queue.run_at
+      `.pipe(
+        Effect.mapError((cause) => queueError("claim", cause)),
+        Effect.tap((rows) =>
+          rows.length === 0 ? Effect.void : Metric.incrementBy(dispatched, rows.length),
+        ),
+      );
+    };
+
+    const execute = (row: QueueRow, leaseMillis: number): Effect.Effect<void> => {
+      const handler: StoredJobHandler | undefined = handlers.get(row.job_name);
+      const context: JobContext = {
+        jobId: row.id,
+        attempt: row.attempt,
+        scheduledFor: runAtOf(row),
+        atLeastOnce: true,
+      };
+      const correlation = Correlation.within({
+        ...(row.correlation_id === null ? {} : { correlationId: row.correlation_id }),
+        causationId: row.id,
+      });
+
+      const heartbeat: Effect.Effect<void> = Effect.gen(function* () {
+        const until = new Date(now().getTime() + leaseMillis);
+        yield* sql`
+          UPDATE ${sql(tables.queue)}
+          SET lease_expires_at = ${until.toISOString()}
+          WHERE id = ${row.id} AND status = 'running'
+        `.pipe(Effect.asVoid);
+      }).pipe(
+        Effect.asVoid,
+        Effect.repeat(Schedule.spaced(`${Math.max(1, Math.floor(leaseMillis / 3))} millis`)),
+        Effect.asVoid,
+        Effect.catchAllCause(() => Effect.void),
+      );
+
+      const runOutcome: Effect.Effect<void> = Effect.gen(function* () {
+        if (handler === undefined) {
+          yield* Effect.logError("job dispatched with no registered handler").pipe(
+            Effect.annotateLogs({ jobId: row.id, jobName: row.job_name }),
+          );
+          yield* deadLetter(row, "unknown-job").pipe(Effect.orDie);
+          return;
+        }
+        const decoded = yield* S.decodeUnknown(handler.payloadSchema)(row.payload).pipe(
+          Effect.either,
+        );
+        if (decoded._tag === "Left") {
+          yield* deadLetter(row, `invalid-payload: ${String(decoded.left).slice(0, 128)}`).pipe(
+            Effect.orDie,
+          );
+          return;
+        }
+        const failure = yield* handler
+          .handle(decoded.right, context)
+          .pipe(Metrics.track(`job_${row.job_name}`, boundaryFor(row.job_name)), Effect.either);
+        if (failure._tag === "Right") {
+          yield* Metric.increment(succeeded);
+          yield* completeSuccess(row).pipe(Effect.orDie);
+          return;
+        }
+        const error = failure.left;
+        yield* Effect.logWarning("job attempt failed").pipe(
+          Effect.annotateLogs({
+            jobId: row.id,
+            jobName: row.job_name,
+            jobAttempt: row.attempt,
+            jobClassification: error.classification,
+            jobReason: error.reason.slice(0, 256),
+          }),
+        );
+        const exhausted = row.attempt >= (row.max_attempts || maxAttemptsFor(row.job_name));
+        if (error.classification === "permanent" || exhausted) {
+          yield* deadLetter(row, error.reason).pipe(Effect.orDie);
+          return;
+        }
+        yield* rescheduleRetry(row, error.reason).pipe(Effect.orDie);
+      });
+
+      return Effect.gen(function* () {
+        const heartbeatFiber = yield* Effect.fork(
+          heartbeat.pipe(Effect.catchAllCause(() => Effect.void)),
+        );
+        yield* runOutcome.pipe(
+          Effect.ensuring(
+            Fiber.interrupt(heartbeatFiber).pipe(
+              Effect.catchAllCause(() => Effect.void),
+              Effect.asVoid,
+            ),
+          ),
+          correlation,
+        );
+      });
+    };
+
+    const runWorker = (workerOptions: WorkerOptions = {}): Effect.Effect<void, never, Shutdown> =>
+      Effect.gen(function* () {
+        const shutdown = yield* Shutdown;
+        const pollMillis =
+          workerOptions.pollInterval === undefined
+            ? 1_000
+            : Duration.toMillis(Duration.decode(workerOptions.pollInterval));
+        const batchSize = workerOptions.batchSize ?? 10;
+        const leaseMillis =
+          workerOptions.lease === undefined
+            ? 60_000
+            : Duration.toMillis(Duration.decode(workerOptions.lease));
+
+        const inflight = new Set<Fiber.RuntimeFiber<void, unknown>>();
+        let stopRequested = false;
+
+        yield* shutdown.onShutdown(
+          "jobs-worker",
+          Effect.sync(() => {
+            stopRequested = true;
+          }).pipe(
+            Effect.zipRight(Effect.logInfo("jobs worker draining")),
+            Effect.zipRight(
+              Effect.whileLoop({
+                while: () => inflight.size > 0,
+                body: () => Effect.sleep("10 millis"),
+                step: () => undefined,
+              }),
+            ),
+          ),
+        );
+
+        const loop: Effect.Effect<void> = Effect.whileLoop({
+          while: () => !stopRequested,
+          body: () =>
+            Effect.gen(function* () {
+              const shuttingDown = yield* shutdown.isShuttingDown;
+              if (shuttingDown) stopRequested = true;
+              if (stopRequested) return;
+              const rows = yield* Effect.orDie(claim(batchSize, leaseMillis));
+              if (rows.length === 0) {
+                yield* Effect.sleep(pollMillis);
+                return;
+              }
+              for (const row of rows) {
+                const fiber = yield* Effect.fork(execute(row, leaseMillis));
+                inflight.add(fiber);
+                void fiber.addObserver(() => inflight.delete(fiber));
+              }
+            }),
+          step: () => undefined,
+        });
+        yield* loop;
+        // Graceful drain: wait for in-flight handlers to finish.
+        yield* Effect.whileLoop({
+          while: () => inflight.size > 0,
+          body: () => Effect.sleep("10 millis"),
+          step: () => undefined,
+        });
+        yield* Effect.logInfo("jobs worker drained").pipe(
+          Effect.annotateLogs({ drained: inflight.size }),
+        );
+      });
+
+    const service: SchedulerService = {
+      register: <P>(handler: JobHandler<P>) =>
+        Effect.sync(() => {
+          handlers.set(handler.name, handler as unknown as StoredJobHandler);
+        }),
+      schedule: (job, payload, scheduleOptions) =>
+        Effect.gen(function* () {
+          const encoded = yield* encodePayload(job.payloadSchema, payload).pipe(
+            Effect.mapError(
+              (cause): InvalidJobPayload =>
+                new InvalidJobPayload({ jobName: job.name, reason: String(cause) }),
+            ),
+          );
+          const jobId = crypto.randomUUID();
+          const correlation =
+            scheduleOptions?.correlationId ??
+            (yield* Effect.map(Correlation.current, (context) => context.correlationId ?? null));
+          const fireAt =
+            scheduleOptions?.delay === undefined
+              ? now()
+              : new Date(
+                  now().getTime() + Duration.toMillis(Duration.decode(scheduleOptions.delay)),
+                );
+          yield* sql`
+            INSERT INTO ${sql(tables.queue)}
+              (id, job_name, payload, status, run_at, attempt, max_attempts,
+               correlation_id, created_at, updated_at)
+            VALUES
+              (${jobId}, ${job.name}, ${encoded}, 'queued', ${fireAt.toISOString()}, 0,
+               ${maxAttemptsFor(job.name)}, ${correlation},
+               ${now().toISOString()}, ${now().toISOString()})
+          `.pipe(Effect.mapError((cause) => queueError("schedule", cause)));
+          yield* Effect.logInfo("job scheduled").pipe(
+            Effect.annotateLogs({ jobId, jobName: job.name, jobRunAt: fireAt.toISOString() }),
+          );
+          return jobId;
+        }),
+      recur: (job, payload, recurOptions) =>
+        Effect.gen(function* () {
+          const fields = yield* parseCron(recurOptions.cron);
+          const encoded = yield* encodePayload(job.payloadSchema, payload).pipe(
+            Effect.mapError(
+              (cause): InvalidJobPayload =>
+                new InvalidJobPayload({ jobName: job.name, reason: String(cause) }),
+            ),
+          );
+          const first = nextRun(now(), fields, recurOptions.timezone ?? "UTC");
+          if (first === undefined) {
+            return yield* new InvalidCronExpression({
+              expression: recurOptions.cron,
+              problems: ["never fires"],
+            });
+          }
+          const jobId = recurOptions.scheduleKey ?? crypto.randomUUID();
+          const correlation =
+            recurOptions.correlationId ??
+            (yield* Effect.map(Correlation.current, (context) => context.correlationId ?? null));
+          yield* sql`
+            INSERT INTO ${sql(tables.queue)}
+              (id, job_name, payload, status, run_at, cron_expr, cron_timezone, attempt,
+               max_attempts, correlation_id, created_at, updated_at)
+            VALUES
+              (${jobId}, ${job.name}, ${encoded}, 'queued', ${first.toISOString()},
+               ${recurOptions.cron}, ${recurOptions.timezone ?? "UTC"}, 0,
+               ${maxAttemptsFor(job.name)}, ${correlation},
+               ${now().toISOString()}, ${now().toISOString()})
+            ON CONFLICT (id) DO UPDATE SET
+              payload = excluded.payload,
+              run_at = excluded.run_at,
+              cron_expr = excluded.cron_expr,
+              cron_timezone = excluded.cron_timezone,
+              status = 'queued',
+              attempt = 0,
+              lease_expires_at = NULL,
+              correlation_id = excluded.correlation_id,
+              updated_at = excluded.updated_at
+          `.pipe(Effect.mapError((cause) => queueError("recur", cause)));
+          yield* Effect.logInfo("recurring job scheduled").pipe(
+            Effect.annotateLogs({
+              jobId,
+              jobName: job.name,
+              jobCron: recurOptions.cron,
+              jobNextRun: first.toISOString(),
+            }),
+          );
+          return jobId;
+        }),
+      cancel: (jobId) =>
+        Effect.asVoid(
+          sql`DELETE FROM ${sql(tables.queue)} WHERE id = ${jobId}`.pipe(
+            Effect.mapError((cause) => queueError("cancel", cause)),
+          ),
+        ),
+      depth: Effect.map(
+        sql<{ readonly count: string }>`
+          SELECT COUNT(*)::text AS count FROM ${sql(tables.queue)}
+        `.pipe(Effect.mapError((cause) => queueError("depth", cause))),
+        (rows) => Number(rows[0]?.count ?? "0"),
+      ),
+      lagMillis: Effect.map(
+        sql<{ readonly lag: string | null }>`
+          SELECT (EXTRACT(EPOCH FROM (${now().toISOString()}::timestamptz - MIN(run_at))) * 1000)::text AS lag
+          FROM ${sql(tables.queue)}
+          WHERE status = 'queued' AND run_at <= ${now().toISOString()}
+        `.pipe(Effect.mapError((cause) => queueError("lag", cause))),
+        (rows) => {
+          const lag = rows[0]?.lag;
+          return lag === null || lag === undefined ? 0 : Math.max(0, Number(lag));
+        },
+      ),
+      registeredJobs: () => [...handlers.keys()],
+      runWorker,
+    };
+    return service;
+  });
+
+/** `Scheduler` layer over an existing `SqlClient` (schema must exist). */
+export const schedulerLayer = (
+  options?: SchedulerOptions,
+): Layer.Layer<Scheduler, never, SqlClient.SqlClient> =>
+  Layer.effect(Scheduler, makeScheduler(options));
+
+/** Decoded failure helper for tests and app-level handlers. */
+export const jobFailure = (
+  reason: string,
+  classification: JobFailure["classification"] = "transient",
+): JobFailure => ({
+  reason,
+  classification,
+});

package/src/schema.ts

@@ -0,0 +1,72 @@
+import * as SqlClient from "@effect/sql/SqlClient";
+import { Effect } from "effect";
+
+export interface AdapterOptions {
+  /** Table name prefix. Defaults to `jobs_`. */
+  readonly tablePrefix?: string;
+}
+
+export interface TableNames {
+  readonly queue: string;
+  readonly deadLetters: string;
+}
+
+export const tableNames = (options: AdapterOptions = {}): TableNames => {
+  const prefix = options.tablePrefix ?? "jobs_";
+  return {
+    queue: `${prefix}queue`,
+    deadLetters: `${prefix}dead_letters`,
+  };
+};
+
+/**
+ * Creates the jobs schema in one transaction, `@structure-ai/migrations`
+ * style (idempotent DDL a designated migrator can run at boot). The queue
+ * index covers the dispatch predicate (`status = queued AND run_at <= now`
+ * plus lease-expiry reclaims).
+ */
+export const migrate = (
+  options: AdapterOptions = {},
+): Effect.Effect<void, never, SqlClient.SqlClient> =>
+  Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const tables = tableNames(options);
+    yield* sql`
+      CREATE TABLE IF NOT EXISTS ${sql(tables.queue)} (
+        id TEXT PRIMARY KEY,
+        job_name TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        status TEXT NOT NULL CHECK (status IN ('queued', 'running')),
+        run_at TIMESTAMPTZ NOT NULL,
+        cron_expr TEXT,
+        cron_timezone TEXT,
+        attempt INTEGER NOT NULL DEFAULT 0,
+        max_attempts INTEGER NOT NULL DEFAULT 5,
+        lease_expires_at TIMESTAMPTZ,
+        last_error TEXT,
+        correlation_id TEXT,
+        causation_id TEXT,
+        created_at TIMESTAMPTZ NOT NULL,
+        updated_at TIMESTAMPTZ NOT NULL
+      )
+    `;
+    yield* sql`
+      CREATE INDEX IF NOT EXISTS ${sql(`${tables.queue}_dispatch_idx`)}
+      ON ${sql(tables.queue)} (status, run_at)
+    `;
+    yield* sql`
+      CREATE INDEX IF NOT EXISTS ${sql(`${tables.queue}_lease_idx`)}
+      ON ${sql(tables.queue)} (status, lease_expires_at)
+    `;
+    yield* sql`
+      CREATE TABLE IF NOT EXISTS ${sql(tables.deadLetters)} (
+        id TEXT PRIMARY KEY,
+        job_name TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        attempts INTEGER NOT NULL,
+        last_error TEXT,
+        correlation_id TEXT,
+        dead_at TIMESTAMPTZ NOT NULL
+      )
+    `;
+  }).pipe(Effect.orDie);

package/src/settings.ts

@@ -0,0 +1,30 @@
+import { Settings } from "@structure-ai/config";
+import { Duration } from "effect";
+
+/**
+ * Standard jobs settings. `SERVICE_ROLE` follows the platform convention:
+ * `api` processes schedule but never run jobs, `worker` processes only run
+ * them, `all` does both.
+ */
+export const jobsSettings = Settings.struct({
+  role: Settings.literal("SERVICE_ROLE", ["api", "worker", "all"], {
+    description: "process role: api schedules only, worker/all also dispatch jobs",
+    default: "all",
+  }),
+  pollInterval: Settings.duration("JOBS_POLL_INTERVAL", {
+    description: "worker idle poll interval",
+    default: Duration.seconds(1),
+  }),
+  batchSize: Settings.int("JOBS_BATCH_SIZE", {
+    description: "jobs claimed per poll",
+    default: 10,
+  }),
+  lease: Settings.duration("JOBS_LEASE", {
+    description: "dispatch lease duration before a running job becomes reclaimable",
+    default: Duration.seconds(60),
+  }),
+  tablePrefix: Settings.string("JOBS_TABLE_PREFIX", {
+    description: "jobs table name prefix",
+    default: "jobs_",
+  }),
+});