@softure-ai/jobs 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+Newest first. Each version lists what changed for an app that uses `@softure-ai/jobs`. When an app has run a version in
+production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
+"Definition of done").
+
+## 0.1.0
+
+- First version (#471): background jobs in Postgres (`jobs.jobs`). `jobs({ queues })` in `softure.config.ts`;
+  `enqueueJob` inside the caller's transaction with an optional `dedupKey`; `cancelJob`, `retryJob`, `getJob`,
+  `getQueueStats`, `pruneJobs`; handlers with a zod payload schema (`defineJobHandler`, `failJob`, `retryJobLater`);
+  `runJobWorker` and `runJobWorkerProcess` (`@softure-ai/jobs/worker`): claim with `FOR UPDATE SKIP LOCKED` under a
+  lease, a heartbeat for long jobs, fenced completion, retry with exponential backoff and jitter, a terminal `failed`
+  state, pruning, and release of unfinished jobs on SIGTERM; `runDueJobs` (`@softure-ai/jobs/testing`) runs due jobs
+  in-process for tests and cron-driven apps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+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

@@ -1,3 +1,225 @@
-# Temporary Holding Version
+# @softure-ai/jobs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Background jobs in Postgres: an app enqueues work in the same transaction as its own write, and a worker process
+runs it with leases, retries and a terminal failure state. Built for the case an adopting app solved by hand (a job
+table of its own and a `scripts/worker.ts` loop): a slow or unreliable call after a request, such as an AI call per
+received message.
+
+## 1. What it provides
+
+A job queue in one table (`jobs.jobs`) with enqueue inside the caller's transaction and dedup keys, claims with
+`FOR UPDATE SKIP LOCKED` under a lease, fenced completion, retry with exponential backoff, a worker process with
+graceful shutdown, and an in-process runner for tests and cron-driven apps.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/jobs @softure-ai/core @softure-ai/db drizzle-orm zod
+```
+
+The worker runs as its own process. With `@softure-ai/deploy`, `softure-deploy init` sees `@softure-ai/jobs` in
+`package.json` and adds `scripts/worker.ts`, its bundle in the image and a `worker` service next to the app (deploy
+README, "Job worker").
+
+## 3. Configuration
+
+```ts
+import { defineSoftureConfig } from "@softure-ai/core";
+import { jobs } from "@softure-ai/jobs";
+
+export default defineSoftureConfig({
+  // database, locale, timezone, appOrigin …
+  modules: [
+    jobs({
+      queues: {
+        "ai.reply": { maxAttempts: 5, backoff: { baseSeconds: 10, maxSeconds: 600 }, leaseSeconds: 120, concurrency: 4 },
+        "mail.digest": {},
+      },
+    }),
+  ],
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `queues.<name>.maxAttempts` | `5` | attempts before a job is `failed`; the first run counts |
+| `queues.<name>.backoff` | `{ baseSeconds: 10, maxSeconds: 3600 }` | delay after attempt n is `min(max, base * 2^(n-1))`, shortened by up to 20 % at random |
+| `queues.<name>.leaseSeconds` | `300` | how long a claimed job is reserved; the worker extends it while the handler runs, so it bounds how long a crashed worker's job waits, not how long a handler may take |
+| `queues.<name>.concurrency` | `1` | jobs of the queue one worker process runs at once |
+| `pollIntervalMs` | `1000` | how often an idle worker looks for due jobs |
+| `shutdownGraceMs` | `20000` | how long a stopping worker waits for running handlers before releasing their jobs |
+| `retention` | `{ succeededDays: 7, failedDays: 30, cancelledDays: 7 }` | how long finished jobs are kept; the worker prunes once an hour |
+
+A queue name is lowercase letters, digits, `_`, `.` and `-`. A queue the config does not define is refused by
+`enqueueJob` and by the worker: a typo is a bug, not a new queue.
+
+### Handlers
+
+One handler per queue, with the zod schema of its payload. The payload read back from the table is parsed with it
+before the handler runs; a payload that does not match fails the job with `jobs.invalid_payload` and is not retried.
+
+```ts
+// src/jobs/handlers.ts
+import { ok } from "@softure-ai/core";
+import { defineJobHandler, failJob, retryJobLater, type JobHandlers } from "@softure-ai/jobs";
+import { z } from "zod";
+
+export const handlers: JobHandlers = {
+  "ai.reply": defineJobHandler({
+    payload: z.object({ messageId: z.string() }),
+    run: async ({ messageId }, { db, signal, job }) => {
+      const message = await findMessage(db, messageId);
+      if (message === null) return failJob("app.message_gone"); // failed at once, no retry
+      const reply = await callModel(message, { signal });
+      if (reply.status === 429) return retryJobLater("app.rate_limited", reply.retryAfterSeconds);
+      if (!reply.ok) return reply; // an Err: retried with the queue's backoff
+      await saveReply(db, messageId, reply.value);
+      return ok();
+    },
+  }),
+};
+```
+
+- `ok()`: done, the job is `succeeded`.
+- An `Err` (any `Result` failure): retried after the backoff delay, until `maxAttempts`; then `failed`.
+- `failJob(code)`: `failed` at once.
+- `retryJobLater(code, seconds)`: retried after `seconds` instead of the backoff (a provider's `Retry-After`); still
+  counts as an attempt.
+- A throw: retried like an `Err` with the code `jobs.handler_threw`, and logged with the error.
+
+**Handlers run at least once.** A worker can die after the side effect and before recording it, a lease can end, a
+stopping worker releases unfinished jobs: the job then runs again. Make handlers idempotent (check whether the reply
+was already saved, pass an idempotency key to the provider).
+
+`context.signal` aborts when the job is taken from the handler: the worker's grace period ended on shutdown, or its
+lease could not be extended. Pass it to `fetch` and other cancellable calls; anything the handler returns afterwards
+is not recorded. `context.db` is the worker's pool, not a transaction; `context.job.attempts` is this attempt's number.
+
+### Enqueueing
+
+```ts
+import { enqueueJob } from "@softure-ai/jobs/server";
+
+await db.transaction(async (tx) => {
+  const [message] = await tx.insert(messages).values(input).returning();
+  await enqueueJob({ db: tx, clock, config }, { queue: "ai.reply", payload: { messageId: message.id }, dedupKey: message.id });
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `queue` | a configured queue |
+| `payload` | JSON for the handler, `{}` when there is none; stored as `jsonb`, so a `Date` comes back as a string. Ids, not personal data |
+| `runAt` / `delaySeconds` | when the job is due; default now; one or the other |
+| `dedupKey` | while a pending or running job of the queue has this key, the call returns that job (`isDuplicate: true`) instead of writing a second one; a finished job frees the key |
+| `maxAttempts` | this job's own limit instead of the queue's |
+
+Inside the caller's transaction the job exists exactly when the caller's change commits; a rolled-back transaction
+leaves no job behind.
+
+### Running the worker
+
+```ts
+// scripts/worker.ts
+import { runJobWorkerProcess } from "@softure-ai/jobs/worker";
+import config from "../softure.config";
+import { handlers } from "../src/jobs/handlers";
+
+await runJobWorkerProcess({ config, handlers });
+```
+
+`runJobWorkerProcess` opens its own pool (`database.url`, or the app's `database.handle`) with one connection per job
+that can run at once plus one, runs the worker until SIGTERM or SIGINT, closes the pool and sets `process.exitCode`
+(0 after a clean stop, 1 when it could not start). Pass `logger: createLogger("jobs")` from
+`@softure-ai/observability` to send its lines to OpenTelemetry; by default they go to the console. `queues: [...]`
+runs only some queues (one worker per queue group).
+
+The worker claims due jobs of every queue it has a handler for, up to each queue's `concurrency`, oldest due first.
+A claim counts as an attempt and takes a lease, which a heartbeat extends while the handler runs. A worker that dies
+leaves its jobs `running` until their lease ends; the next claim then takes them over (or fails them with
+`jobs.lease_expired` when no attempt is left). Every write after a claim is fenced by a claim token, so the worker
+whose lease was taken over cannot record an outcome over the newer attempt. Several workers can run side by side:
+`SKIP LOCKED` hands each job to one of them.
+
+On SIGTERM the worker stops claiming, waits up to `shutdownGraceMs` for running handlers, then aborts the rest and
+releases their jobs (pending again, due now, the attempt given back). Database errors while claiming or recording are
+logged and retried on the next round; a database restart does not end the worker.
+
+`runJobWorker({ db, config, handlers, signal })` is the loop without the process part, for an app that runs it inside
+a process of its own.
+
+### Without a worker
+
+`runDueJobs(ctx, { handlers })` (from `@softure-ai/jobs/server` or `/testing`) runs every due job once, in this process,
+one after another, and returns `{ succeeded, retried, failed, stale }`. A cron can drain a queue with it; call
+`pruneJobs(ctx)` from the same cron.
+
+### Steering and overview
+
+From `@softure-ai/jobs/server`, each on `ctx = { db, clock, config }`:
+
+| Function | Result |
+| --- | --- |
+| `getJob(ctx, id)` | the `Job` or `null` |
+| `cancelJob(ctx, id)` | a pending job becomes `cancelled`; `jobs.not_cancellable` for a running or finished one, `jobs.not_found` |
+| `retryJob(ctx, id)` | a failed or cancelled job runs again from scratch (attempts 0, due now); `jobs.not_retryable`, `jobs.dedup_key_taken` while a live job has its key, `jobs.not_found` |
+| `getQueueStats(ctx)` | per queue: counts per status, the due backlog and the `run_at` of its oldest due job |
+| `pruneJobs(ctx)` | deletes finished jobs past their retention; returns the count |
+
+`getQueueStats` suits an app health check of its own, `ops({ checks: { "app.jobs": … } })`, e.g. unavailable when the
+oldest due job of a queue waited more than ten minutes (no worker is running). An ops script (`@softure-ai/ops/scripts`)
+can wrap `retryJob` and `cancelJob` for the operator.
+
+## 4. Mounting
+
+Nothing to mount: the module has no routes or pages. The worker is a process (§3, "Running the worker").
+
+## 5. Migrations and tables
+
+Schema `jobs`, one table, `migrations/0001_create_jobs.sql`:
+
+`jobs.jobs`: `id` (bigint identity; a string in the API), `queue`, `payload` (jsonb), `status` (`pending`, `running`,
+`succeeded`, `failed`, `cancelled`), `attempts`, `max_attempts`, `run_at`, `locked_until`, `locked_by` (the worker,
+`<hostname>:<pid>`), `claim_token`, `dedup_key`, `last_error` (an error code, never a message), `created_at`,
+`updated_at`, `finished_at`. Checks keep the lease columns set exactly while `running` and `finished_at` set exactly
+for finished jobs; a partial unique index allows one live job per queue and dedup key.
+
+The app role needs `SELECT, INSERT, UPDATE, DELETE` on the table, which the `@softure-ai/ops` roles recipe grants on
+every schema the migrator creates.
+
+## 6. Environment variables
+
+None of its own. The worker reads the app's config, so it gets the app's `DATABASE_URL` and whatever its handlers need.
+
+## 7. Switches
+
+None.
+
+## 8. Appearance
+
+No UI.
+
+## 9. Copy
+
+`errors.*` in `src/messages/en.ts`, one key per error code (`invalid_payload`, `handler_threw`, `lease_expired`,
+`not_found`, `not_cancellable`, `not_retryable`, `dedup_key_taken`), for an admin screen that shows a job's state.
+
+## 10. Hooks
+
+The handlers (§3) are the app's code. `logger` (`info`, `warn`, `error`; `@softure-ai/observability`'s `Logger` fits)
+receives the worker's lines: started, stopped, a thrown handler with its error, a lost lease, a release, pruning.
+
+## 11. GDPR
+
+No export or deletion contributor: jobs are transient and pruned (§3, `retention`). Keep personal data out of
+payloads (ids only); then a deleted account leaves nothing personal in `jobs.jobs`. `last_error` holds codes, and the
+logger gets payload paths, never values, for a payload that does not match its schema.
+
+## 12. Limitations
+
+- Polling, no `LISTEN/NOTIFY`: a job waits up to `pollIntervalMs` when the worker is idle.
+- No cron schedules or recurring jobs: a cron (or a handler that enqueues its next run) does that.
+- No priorities within a queue and no rate limits per queue beyond `concurrency`; split work into queues instead.
+- At-least-once delivery (§3, "Handlers run at least once").
+- PGlite has one connection, so tests run claims one after another; concurrent claiming is Postgres behaviour
+  (`SKIP LOCKED`) and is not exercised in unit tests.

package/dist/contract.d.ts

@@ -0,0 +1,48 @@
+import type { Err, ErrorCode } from "@softure-ai/core";
+export type JobsErrorCode = "jobs.invalid_payload" | "jobs.handler_threw" | "jobs.lease_expired" | "jobs.not_found" | "jobs.not_cancellable" | "jobs.not_retryable" | "jobs.dedup_key_taken";
+export declare const JOB_STATUSES: readonly ["pending", "running", "succeeded", "failed", "cancelled"];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+/** One job as the module's functions return it. */
+export interface Job {
+    readonly id: string;
+    readonly queue: string;
+    readonly payload: unknown;
+    readonly status: JobStatus;
+    /** Claims so far; the running attempt's number while `running`. */
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    /** When a pending job is due. */
+    readonly runAt: Date;
+    readonly lockedUntil: Date | null;
+    readonly lockedBy: string | null;
+    readonly dedupKey: string | null;
+    /** The error code of the last failed attempt. */
+    readonly lastError: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly finishedAt: Date | null;
+}
+/**
+ * A handler's failure. Retried with the queue's backoff unless `retry` is false or the attempts are used up;
+ * `retryAfterSeconds` replaces the backoff delay for this attempt (a provider's `Retry-After`).
+ */
+export type JobFailure = Err<ErrorCode> & {
+    readonly retry?: boolean;
+    readonly retryAfterSeconds?: number;
+};
+/** What happened to a job after one attempt. */
+export type JobOutcome = {
+    readonly kind: "succeeded";
+} | {
+    readonly kind: "retried";
+    readonly error: string;
+    readonly runAt: Date;
+} | {
+    readonly kind: "failed";
+    readonly error: string;
+}
+/** The job was taken over (lease ended) or released before the attempt finished; nothing was recorded. */
+ | {
+    readonly kind: "stale";
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,sBAAsB,GACtB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,eAAO,MAAM,YAAY,qEAAsE,CAAC;AAEhG,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,mDAAmD;AACnD,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACrD,0GAA0G;GACxG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export const JOB_STATUSES = ["pending", "running", "succeeded", "failed", "cancelled"];
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAaA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC"}

package/dist/handlers.d.ts

@@ -0,0 +1,60 @@
+import type { Clock, ErrorCode, Ok, SoftureConfig } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import type { z } from "zod";
+import type { Job, JobFailure } from "./contract.js";
+/** What a handler receives besides its payload. */
+export interface JobHandlerContext {
+    /** The worker's database: not a transaction; open one with `db.transaction` when the work needs it. */
+    readonly db: Queryable;
+    readonly clock: Clock;
+    readonly config: SoftureConfig;
+    /** The job as claimed: `attempts` is this attempt's number, starting at 1. */
+    readonly job: Job;
+    /**
+     * Aborted when the job is taken away from this handler: the worker stops and its grace period ended, or the lease
+     * could not be extended. Pass it to `fetch` and other cancellable calls; whatever the handler returns afterwards is
+     * not recorded.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * What a handler returns: `ok()` when the work is done; an `Err` to try again with the queue's backoff (until the
+ * attempts are used up); `failJob(code)` to fail for good; `retryJobLater(code, seconds)` to try again after a delay
+ * the handler chooses. A throw is retried like an `Err` with the code `jobs.handler_threw` and logged.
+ */
+export type JobRunResult = Ok<unknown> | JobFailure;
+export interface JobHandler<TPayload = unknown> {
+    /** The schema of the payload; a payload that does not match fails the job with `jobs.invalid_payload`, untried. */
+    readonly payload: z.ZodType<TPayload>;
+    readonly run: (payload: TPayload, context: JobHandlerContext) => Promise<JobRunResult>;
+}
+/**
+ * A handler of any payload type, as a handler map holds it. `run` takes `never` so every `JobHandler<T>` fits; the
+ * runner passes it the payload its own schema parsed.
+ */
+export interface AnyJobHandler {
+    readonly payload: z.ZodType;
+    readonly run: (payload: never, context: JobHandlerContext) => Promise<JobRunResult>;
+}
+/** Handlers by queue name. Every queue a worker runs needs one; a handler for an unknown queue is refused. */
+export type JobHandlers = Readonly<Record<string, AnyJobHandler>>;
+/**
+ * Defines a handler with its payload type inferred from the schema:
+ *
+ *   export const replyHandler = defineJobHandler({
+ *     payload: z.object({ messageId: z.string() }),
+ *     run: async ({ messageId }, { db }) => { ...; return ok(); },
+ *   });
+ */
+export declare function defineJobHandler<TSchema extends z.ZodType>(handler: {
+    readonly payload: TSchema;
+    readonly run: (payload: z.output<TSchema>, context: JobHandlerContext) => Promise<JobRunResult>;
+}): JobHandler<z.output<TSchema>>;
+/** A failure that is not retried: the job is `failed` at once with this code. */
+export declare function failJob<E extends ErrorCode>(error: E): JobFailure;
+/**
+ * A failure retried after `seconds` instead of the queue's backoff (a provider's `Retry-After`). Still counts as an
+ * attempt: after the last one the job is `failed`.
+ */
+export declare function retryJobLater<E extends ErrorCode>(error: E, seconds: number): JobFailure;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAErD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,uGAAuG;IACvG,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,UAAU,CAAC,QAAQ,GAAG,OAAO;IAC5C,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACxF;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACrF;AAED,8GAA8G;AAC9G,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACjG,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAKhC;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAEjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAKxF"}

package/dist/handlers.js

@@ -0,0 +1,29 @@
+/**
+ * Defines a handler with its payload type inferred from the schema:
+ *
+ *   export const replyHandler = defineJobHandler({
+ *     payload: z.object({ messageId: z.string() }),
+ *     run: async ({ messageId }, { db }) => { ...; return ok(); },
+ *   });
+ */
+export function defineJobHandler(handler) {
+    if (typeof handler.run !== "function") {
+        throw new Error("defineJobHandler: run must be a function");
+    }
+    return handler;
+}
+/** A failure that is not retried: the job is `failed` at once with this code. */
+export function failJob(error) {
+    return { ok: false, error, retry: false };
+}
+/**
+ * A failure retried after `seconds` instead of the queue's backoff (a provider's `Retry-After`). Still counts as an
+ * attempt: after the last one the job is `failed`.
+ */
+export function retryJobLater(error, seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError(`retryJobLater: seconds must be a finite number >= 0, got ${String(seconds)}`);
+    }
+    return { ok: false, error, retryAfterSeconds: seconds };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAgDA;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAA4B,OAG3D;IACC,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,OAAwC,CAAC;AAClD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAsB,KAAQ;IACnD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAsB,KAAQ,EAAE,OAAe;IAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,UAAU,CAAC,4DAA4D,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export declare const MODULE_ID = "jobs";
+/**
+ * Enables background jobs in `softure.config.ts`: `jobs({ queues: { "ai.reply": { maxAttempts: 5 } } })`. Jobs run
+ * in a worker process (`runJobWorkerProcess` from `@softure-ai/jobs/worker`).
+ */
+export declare const jobs: import("@softure-ai/core").ModuleFactory<{}, {
+    errors: {
+        invalid_payload: string;
+        handler_threw: string;
+        lease_expired: string;
+        not_found: string;
+        not_cancellable: string;
+        not_retryable: string;
+        dedup_key_taken: string;
+    };
+}, import("zod").ZodObject<{
+    queues: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
+        maxAttempts: import("zod").ZodDefault<import("zod").ZodNumber>;
+        backoff: import("zod").ZodDefault<import("zod").ZodObject<{
+            baseSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+            maxSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+        }, import("zod/v4/core").$strict>>;
+        leaseSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+        concurrency: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>>;
+    pollIntervalMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    shutdownGraceMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    retention: import("zod").ZodDefault<import("zod").ZodObject<{
+        succeededDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+        failedDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+        cancelledDays: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>>;
+}, import("zod/v4/core").$strict>>;
+export { JOB_STATUSES, type Job, type JobFailure, type JobOutcome, type JobsErrorCode, type JobStatus, } from "./contract.js";
+export { jobsMessages, type JobsMessages } from "./messages/index.js";
+export { jobsOptionsSchema, type JobQueueOptions, type JobsOptions, type JobsOptionsInput } from "./options.js";
+export { defineJobHandler, failJob, retryJobLater, type JobHandler, type JobHandlerContext, type JobHandlers } from "./handlers.js";
+export { jobs as jobsTable } from "./schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAiBf,CAAC;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpI,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+// Public API of @softure-ai/jobs: the module factory for softure.config.ts, the handler helpers and the types.
+// Database work is in `@softure-ai/jobs/server`, the worker in `@softure-ai/jobs/worker`, the in-process runner for
+// tests in `@softure-ai/jobs/testing`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { jobsMessages } from "./messages/index.js";
+import { jobsOptionsSchema } from "./options.js";
+import { checkJobsTable } from "./server/health.js";
+export const MODULE_ID = "jobs";
+/**
+ * Enables background jobs in `softure.config.ts`: `jobs({ queues: { "ai.reply": { maxAttempts: 5 } } })`. Jobs run
+ * in a worker process (`runJobWorkerProcess` from `@softure-ai/jobs/worker`).
+ */
+export const jobs = defineModule({
+    manifest: {
+        id: MODULE_ID,
+        version: "0.1.0",
+        dependsOn: {},
+        dbSchema: "jobs",
+        tables: ["jobs"],
+        env: [],
+        switches: [],
+        routes: {},
+        mount: [],
+        privacy: { exports: false, deletes: false },
+    },
+    messages: jobsMessages,
+    options: jobsOptionsSchema,
+    migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+    health: checkJobsTable,
+});
+export { JOB_STATUSES, } from "./contract.js";
+export { jobsMessages } from "./messages/index.js";
+export { jobsOptionsSchema } from "./options.js";
+export { defineJobHandler, failJob, retryJobLater } from "./handlers.js";
+export { jobs as jobsTable } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,oHAAoH;AACpH,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AAEhC;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,YAAY,CAAC;IAC/B,QAAQ,EAAE;QACR,EAAE,EAAE,SAAS;QACb,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,EAAE;QACb,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,CAAC,MAAM,CAAC;QAChB,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,EAAE;QACT,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;KAC5C;IACD,QAAQ,EAAE,YAAY;IACtB,OAAO,EAAE,iBAAiB;IAC1B,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE;IAC5E,MAAM,EAAE,cAAc;CACvB,CAAC,CAAC;AAEH,OAAO,EACL,YAAY,GAMb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAiE,MAAM,cAAc,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAA6D,MAAM,eAAe,CAAC;AACpI,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/messages/en.d.ts

@@ -0,0 +1,12 @@
+export declare const en: {
+    errors: {
+        invalid_payload: string;
+        handler_threw: string;
+        lease_expired: string;
+        not_found: string;
+        not_cancellable: string;
+        not_retryable: string;
+        dedup_key_taken: string;
+    };
+};
+//# sourceMappingURL=en.d.ts.map

package/dist/messages/en.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;;;;;;CAUd,CAAC"}

package/dist/messages/en.js

@@ -0,0 +1,12 @@
+export const en = {
+    errors: {
+        invalid_payload: "The job's data is not valid.",
+        handler_threw: "The job failed unexpectedly. It will be tried again.",
+        lease_expired: "The job did not finish in time.",
+        not_found: "The job does not exist.",
+        not_cancellable: "Only a job that has not started can be cancelled.",
+        not_retryable: "Only a failed or cancelled job can be run again.",
+        dedup_key_taken: "Another job for the same work is already waiting or running.",
+    },
+};
+//# sourceMappingURL=en.js.map

package/dist/messages/en.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,eAAe,EAAE,8BAA8B;QAC/C,aAAa,EAAE,sDAAsD;QACrE,aAAa,EAAE,iCAAiC;QAChD,SAAS,EAAE,yBAAyB;QACpC,eAAe,EAAE,mDAAmD;QACpE,aAAa,EAAE,kDAAkD;QACjE,eAAe,EAAE,8DAA8D;KAChF;CACF,CAAC"}

package/dist/messages/index.d.ts

@@ -0,0 +1,17 @@
+import { en } from "./en.js";
+/** The built-in English dictionary; an app passes partial overrides or its own translation per locale. */
+export declare const jobsMessages: {
+    en: {
+        errors: {
+            invalid_payload: string;
+            handler_threw: string;
+            lease_expired: string;
+            not_found: string;
+            not_cancellable: string;
+            not_retryable: string;
+            dedup_key_taken: string;
+        };
+    };
+};
+export type JobsMessages = typeof en;
+//# sourceMappingURL=index.d.ts.map

package/dist/messages/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,0GAA0G;AAC1G,eAAO,MAAM,YAAY;;;;;;;;;;;;CAAS,CAAC;AAEnC,MAAM,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC"}

package/dist/messages/index.js

@@ -0,0 +1,4 @@
+import { en } from "./en.js";
+/** The built-in English dictionary; an app passes partial overrides or its own translation per locale. */
+export const jobsMessages = { en };
+//# sourceMappingURL=index.js.map

package/dist/messages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,0GAA0G;AAC1G,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,EAAE,EAAE,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const jobsOptionsSchema: z.ZodObject<{
+    queues: z.ZodRecord<z.ZodString, z.ZodObject<{
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+        backoff: z.ZodDefault<z.ZodObject<{
+            baseSeconds: z.ZodDefault<z.ZodNumber>;
+            maxSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        leaseSeconds: z.ZodDefault<z.ZodNumber>;
+        concurrency: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    pollIntervalMs: z.ZodDefault<z.ZodNumber>;
+    shutdownGraceMs: z.ZodDefault<z.ZodNumber>;
+    retention: z.ZodDefault<z.ZodObject<{
+        succeededDays: z.ZodDefault<z.ZodNumber>;
+        failedDays: z.ZodDefault<z.ZodNumber>;
+        cancelledDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type JobsOptionsInput = z.input<typeof jobsOptionsSchema>;
+export type JobsOptions = z.output<typeof jobsOptionsSchema>;
+export type JobQueueOptions = JobsOptions["queues"][string];
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyCxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;kBAiB5B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC"}