-spec archive_jobs(atom(), pos_integer()) -> {ok, non_neg_integer()} | {error, term()}.

Archive completed/discarded/cancelled jobs older than given days. Moves to archive table then deletes.

-spec cancel_by(atom(), map()) -> {ok, non_neg_integer()} | {error, term()}.

Cancel jobs matching a pattern. Supports worker, queue, tags filters.

-spec cancel_job(atom(), integer()) -> ok | {error, term()}.

Cancel a job. Resolves dependencies so dependent jobs aren't stuck.

-spec claim_jobs(atom(), binary(), pos_integer()) -> {ok, [map()]} | {error, term()}.

Claim up to N available jobs from a queue using FOR UPDATE SKIP LOCKED.

-spec claim_jobs_fair(atom(), binary(), pos_integer()) -> {ok, [map()]} | {error, term()}.

Claim jobs with fair partition interleaving. One job per partition first, then fill.

-spec complete_job(atom(), integer()) -> ok | {error, term()}.

Mark a job as completed with no result. Equivalent to complete_job/3 with null.

-spec complete_job(atom(), integer(), term()) -> ok | {error, term()}.

Mark a job as completed and store its JSON-encodable result on the row.

The result is propagated to any jobs that depend on this one (see resolve_dependencies/2) so they can read it via deps_results.

-spec discard_job(atom(), integer()) -> ok | {error, term()}.

Mark a job as discarded. Resolves dependencies so dependent jobs aren't stuck.

-spec fail_job(atom(), map(), term(), pos_integer()) -> ok | {error, term()}.

Record a job failure with structured error and configurable backoff.

-spec fetch_fanout_jobs(atom(), binary(), pos_integer()) -> {ok, [map()]} | {error, term()}.

Fetch recent jobs for fanout queues. No locking — all nodes read the same rows.

-spec find_jobs(atom(), map()) -> {ok, [map()]} | {error, term()}.

Find jobs matching a filter map. Read-only; used by the testing helpers' DB-backed enqueue assertions.

Filters: worker, queue, args (jsonb containment), tags (array containment), and state (a state binary or a list of them). An empty filter returns all jobs. Args are decrypted so callers can match on plaintext.

-spec get_due_cron_entries(atom()) -> {ok, [map()]} | {error, term()}.

Get cron entries that are due for scheduling.

-spec get_job(atom(), integer()) -> {ok, map()} | {error, not_found | term()}.

Get a job by ID.

-spec insert_all(atom(), [map()], map()) -> {ok, [map()]} | {error, term()}.

Bulk insert multiple jobs in a single SQL statement. Returns inserted jobs.

-spec insert_job(atom(), map(), map()) -> {ok, map()} | {ok, {conflict, map()}} | {error, term()}.

Insert a new job. Respects worker defaults and unique constraints. Validates dependency cycles.

-spec prune_archive(atom(), pos_integer()) -> {ok, non_neg_integer()} | {error, term()}.

Delete archived jobs older than given days. Bounds the archive table.

-spec prune_jobs(atom(), pos_integer()) -> {ok, non_neg_integer()} | {error, term()}.

Delete completed/discarded jobs older than given days.

-spec rescue_stale_jobs(atom(), pos_integer()) -> {ok, non_neg_integer()} | {error, term()}.

Rescue stale executing jobs. Uses heartbeat if available, otherwise attempted_at.

-spec resolve_dependencies(atom(), integer()) -> {ok, non_neg_integer()} | {error, term()}.

Resolve dependencies of a finished job.

Removes the finished job ID from every dependent's depends_on array (which ungates the dependent once its last predecessor clears) and records the finished job's result under its ID in each dependent's deps_results. A job that produced no result (plain completion, discard, or cancel) contributes a JSON null.

-spec retry_by(atom(), map()) -> {ok, non_neg_integer()} | {error, term()}.

Retry all jobs matching a filter. Supports worker, queue, state, tags.

-spec retry_job(atom(), integer()) -> ok | {error, term()}.

Retry a discarded or cancelled job by resetting to available.

-spec snooze_job(atom(), integer(), pos_integer()) -> ok | {error, term()}.

Snooze a job — reschedule for later without counting as a failure.

-spec update_progress(atom(), integer(), 0..100) -> ok | {error, term()}.

Update job progress (0-100).

-spec upsert_cron_entry(atom(), map()) -> ok | {error, term()}.

Upsert a cron entry.