# `Tay`
[🔗](https://github.com/AndriiSydorenko1904/tay/blob/v1.6.1/lib/tay.ex#L1)

An embedded background job engine supporting persistent and volatile jobs.
For persistent jobs, the append-only Store-v2 journal is authoritative and
ETS indexes are disposable projections rebuilt during recovery. Volatile jobs
use the same state machine and execution paths but exist only in RAM/ETS,
never enter persistent storage, and disappear when the Engine's in-memory
state is lost.

Start an Engine explicitly; application startup only validates configuration
and starts an empty supervisor.

Tay supports selective-durability insertion, supervised multi-queue execution,
scheduling, retries, revision-checked cancellation and manual retry, volatile
queue controls, drain, and explicit fresh-generation stop/restart. Callback
effects are at-least-once, not exactly-once. Cancellation durably fences future
persistent outcomes before best-effort termination; volatile cancellation is
enforced only by the current in-memory state. Neither can reverse external
effects.

Physical framing validity is separate from Event support and state replay.
Torn, corrupt or unsupported history preserves evidence and refuses writable
activation; there is no automatic repair or partial-state publication.
Submitted calls with lost replies can have unknown outcomes and are not
automatically retried.

By default, initialize storage explicitly with `Tay.Storage.initialize/1`, then
supervise `Tay.child_spec/1`. Callers may opt into `initialize: :if_missing`
to initialize only a genuinely missing root before normal recovery. It is
never a repair or recovery fallback. Engine options are not `:tay_core`
application environment keys.
`:sync` requires an explicitly validated Linux filesystem; explicit `:write`
is a development mode and is never described as durable.

# `cancel`

Durably cancels an eligible job. Options are `:name`, `:timeout`, and
`:expected_revision` (the opaque token from a job view). If the revision option
is omitted, lookup captures it once. A timeout after submission is an unknown
outcome carrying that exact token; reconcile explicitly before a new command.

# `cancel_schedule`

Durably cancels a recurring schedule.

# `child_spec`

# `compact`

Builds a Store-v2 replacement in the background while ordinary admission and
execution continue, then performs a fenced epoch switch. Uses the Engine's
bounded terminal retention by default. Administrative
`terminal_retention: :infinity` retains all jobs; `{:minutes, n}` or
`{:hours, n}` overrides the bounded duration. Zero removes every terminal job
while preserving all active jobs. No override bypasses the
publication fence, headroom, or exact validation.

# `default_name`

Returns the registered name used by Tay APIs when `:name` is omitted.

# `drain`

Rejects new inserts/claims and waits for durable settlement and local task death.
Queued jobs need not execute. Timeout leaves the Engine draining. A submitted
transport timeout is an unknown control outcome, never implicit resumption.

# `enqueue`

Enqueues a portable task for a currently configured Protocol v1 listener.

`task` is a stable UTF-8 capability name, not an Elixir module name.  `args`
must be a JSON-compatible string-keyed map.  A supplied 128-bit lowercase
hexadecimal `:id` is also the idempotency key: repeat the exact submission
after an unknown outcome rather than allocating another ID.

# `get_job`

# `insert`

# `insert`

# `jobs`

Returns a bounded, cursor-paginated page of public job views.

# `pause_queue`

Stops new claims for a configured queue after the accepted barrier. Volatile.

# `queues`

Returns configured queues and their current volatile runtime state.

# `restart`

Explicitly replaces the execution generation using fresh full recovery and the
original validated startup configuration. Never replays a pending client RPC.
Options: name, timeout, force. Change configuration via host-child replacement.

# `resume_queue`

Resumes a configured queue; it does not undo an Engine drain.

# `retry`

Expedites retryable work or starts a new cycle for discarded work, retaining
its immutable definition. Uses the same options and one-capture revision
semantics as `cancel/2`. Completed/cancelled/available/executing jobs conflict.

# `schedules`

Returns all durable recurring schedules.

# `start_link`

# `stats`

Returns an efficient count snapshot for every public job state.

# `status`

# `stop`

Drains then stops the execution generation, retaining its host-supervised
lifecycle coordinator. `force: true` explicitly skips drain and revokes active
execution; it is not a successful drain. Options: name, timeout, force.

# `storage_records`

Returns bounded physical metadata and decoded inspection previews for one storage segment.

---

*Consult [api-reference.md](api-reference.md) for complete listing*