@spec ensure_scheduled() :: {:ok, Oban.Job.t()} | {:error, term()}

Ensures a tick is scheduled (or already is — see the moduledoc on unique:). Unconditional: does not check sweep_enabled?/0, because the chain itself is meant to run forever once started (see moduledoc).

Called on shop enable_system/0, after a sweep-settings save (reschedule/0), and on the management page's mount/3.

@spec last_run() :: map() | nil

The persisted outcome of the most recent tick — nil before the first tick has ever run. Shape: %{"reason" => string, "at" => iso8601 string, ...}; the extra keys vary by reason (see run_tick/0's docs for the reason list). This is how the management page (next task) shows "why the sweep last stopped" without re-deriving it live — status/0 below is the live version, for "is it configured to run at all right now".

@spec next_tick_at() :: DateTime.t() | nil

The scheduled_at of the pending tick, if any (design §4.5: "следующий тик в HH:MM").

@spec reschedule() :: {:ok, Oban.Job.t()} | {:error, term()}

Cancels whatever tick is currently scheduled (an available tick — one already due to run — is left alone; it will read the new interval when scheduling ITS successor) and schedules a fresh one at the currently-configured interval.

Design §4.3: a settings save must call this, or a shortened interval (say 60 minutes down to 5) would not take effect until the stale 60-minute wait finished.

@spec run_manual_tick() :: {atom(), map()}

Manual twin of run_tick/0, for the management page's "Запустить сверку" button — called directly for immediate feedback, without disturbing the scheduled tick (an Oban-inserted immediate job would just collide with the same uniqueness that keeps the chain single-instance).

Owner decision overriding design §4.5 as written: shop_translation_sweep_enabled gates AUTOMATIC scheduling only. An operator-initiated run performs the tick's work regardless of that setting — the documented manual-only mode (badge: "Automatic sweep: off (manual only)") would otherwise make its own "Run sweep" button refuse to run. Every OTHER gate (AI availability, the in-flight ceiling, target languages) still applies exactly as it does for the scheduled tick.

@spec run_tick() :: {atom(), map()}

The tick's body, with the scheduling step removed — this is what perform/1 runs after scheduling its successor. This is the AUTOMATIC path: it stops (:sweep_disabled) when shop_translation_sweep_enabled is off, exactly as before. The management page's "Запустить сверку" button calls run_manual_tick/0 below instead, not this function.

Returns {reason, info} — reason is one of :translations_disabled, :product_source_unsupported (the shop reads products from the catalogue, so no shop adapter is registered with phoenix_kit_ai and every job would be discarded — see PhoenixKitEcommerce.translations_supported?/0), :sweep_disabled, :ai_unavailable, :sweep_stalled (Fix C: the tick selected nothing AND the configured batch/ceiling guarantees every future tick will do the same until they change — see structurally_stalled?/3), :ceiling_reached, :no_target_languages, or :ok (ran; info[:enqueued] may still be 0 if nothing needed translating or everything was already in flight — that 0 is never ambiguous with a structural stall, which always gets its own reason above). Every outcome is also persisted — see last_run/0.

@spec status() :: %{next_tick_at: DateTime.t() | nil, last_run: map() | nil}

Live scheduling status — next_tick_at/0 plus last_run/0 — bundled for the management page's sweep block (design §4.5).

@spec structurally_stalled?(non_neg_integer(), non_neg_integer(), [String.t()]) ::
  boolean()

Fix C: true when batch_size/max_in_flight, as currently configured, cannot be relied on to ever let take_within_budget/3 select a candidate — independent of any particular tick's in-flight count or candidate list.

take_within_budget/3 HALTS — never skips — on the first candidate whose language count exceeds the remaining job budget:

• batch_size < 1 — its resource_budget starts at or below zero, so the very first check in its reduce_while halts before looking at any candidate at all. NOTHING is selectable, ever.
• max_in_flight < 1 — the in-flight ceiling can never leave a positive job budget for any tick to spend, whatever is or isn't currently running. Again nothing is selectable, ever.
• max_in_flight < length(target_langs) — a resource missing every configured target language (the worst case, and an entirely ordinary one: any newly added or bulk-imported resource starts there) needs length(target_langs) jobs; a ceiling below that can never admit it, and because the scan halts rather than skips, it blocks every cheaper candidate queued behind it too. Note the narrower claim: this arm does NOT make selection impossible — a candidate whose own language gap fits under the ceiling and sorts ahead of any such blocker is still enqueued, and run_tick/0 deliberately keeps enqueueing it rather than refusing to sweep.

So this predicate answers "is an empty tick under this config permanent rather than incidental?" — run_tick/0 records :sweep_stalled when it holds AND the tick selected nothing, so that emptiness stops reading as a healthy idle sweep. It is not, by itself, a licence to skip the work.

@spec take_within_budget([map()], non_neg_integer(), non_neg_integer()) :: [map()]

Design §4.3: the limit is counted in JOBS (one per candidate language), not resources — job_budget — while resource_budget (shop_translation_batch) independently caps how many resources a single tick touches. Selection stops BEFORE either running total would be exceeded, never partially consuming a candidate's language list.