# hourglass v0.1.0 - Table of Contents

> A standalone Elixir SDK for Temporal: workflow and activity definitions, a worker that polls a Temporal cluster, a client, a deterministic replayer, and a Rust NIF bridge over temporalio-sdk-core.

## Modules

- [Hourglass](Hourglass.md): Hourglass — a standalone Elixir SDK for Temporal (https://temporal.io).
- [Hourglass.Activity](Hourglass.Activity.md): Activity-side `use` macro. Activities are plain Elixir modules —
no determinism constraint. Each activity module implements
`execute(input)` and is dispatched by the runner based on its
module name (the activity_type). The runner calls `execute/1` with
the deserialized input.
- [Hourglass.Activity.Behaviour](Hourglass.Activity.Behaviour.md): Behaviour activities implement to be dispatched by
`Hourglass.ActivityRunner`.
- [Hourglass.Activity.Info](Hourglass.Activity.Info.md): Per-dispatch context the runner threads through
`Hourglass.Activity.info/0`.
- [Hourglass.Activity.RetryClassifier](Hourglass.Activity.RetryClassifier.md): Behaviour for classifying an activity failure into a Temporal retry verdict.
- [Hourglass.Activity.RetryClassifier.Default](Hourglass.Activity.RetryClassifier.Default.md): Permissive default classifier: every failure is `:retryable`. Hosts that need
non-retryable verdicts for specific error shapes configure their own module
via `config :hourglass, :retry_classifier`.

- [Hourglass.ActivityExecutor.DynamicSupervisor](Hourglass.ActivityExecutor.DynamicSupervisor.md): Application-level shared `DynamicSupervisor` for ephemeral activity
executor Tasks. Each child wraps `Hourglass.ActivityRunner.run/3`
(called via the 2-arg form, which fills in the default
`complete_fn` arg pointing at `BridgeHolder.complete_activity_task/2`).
- [Hourglass.ActivityRunner](Hourglass.ActivityRunner.md): Runs a single activity task. Spawned by the
`Hourglass.ActivityExecutor.DynamicSupervisor` as a Task;
invokes `<activity_module>.handle(name, args)`; classifies the
outcome through `Hourglass.Activity.RetryClassifier`;
wraps the result into an `ActivityTaskCompletion` proto; ships back
via `Hourglass.BridgeHolder.complete_activity_task/2`.
- [Hourglass.Application](Hourglass.Application.md): OTP Application entry point for the Hourglass Temporal SDK.
- [Hourglass.Bridge](Hourglass.Bridge.md): Rustler NIF wrapper for the hourglass crate.
- [Hourglass.Bridge.Error](Hourglass.Bridge.Error.md): Tagged failure values returned from the bridge layer.
- [Hourglass.BridgeHolder](Hourglass.BridgeHolder.md): Application-level resource manager for per-task-queue Temporal-bridge
worker handles. A single long-lived `GenServer` started under
`Hourglass.Application` that owns every bridge handle in the VM and
mediates every NIF call against them.
- [Hourglass.Check.WorkflowDeterminism](Hourglass.Check.WorkflowDeterminism.md): ## Basics
- [Hourglass.Client](Hourglass.Client.md): Client-side workflow operations. Wraps `Hourglass.Bridge.client_*`
NIFs; translates `%Bridge.Error{}` to higher-level `%Error{}` reasons.

- [Hourglass.Client.Backend](Hourglass.Client.Backend.md): Behaviour describing the cluster-facing operations Hourglass code issues
through `Hourglass.Client`.
- [Hourglass.Client.Real](Hourglass.Client.Real.md): Production `Hourglass.Client.Backend` implementation. Wraps the
Bridge NIFs to round-trip real Temporal Server.
- [Hourglass.Codec](Hourglass.Codec.md): The typed-payload boundary for Hourglass workflow/activity I/O.
- [Hourglass.Error](Hourglass.Error.md): Higher-level error returned from `Hourglass.*` facade calls.
Distinct from `Hourglass.Bridge.Error` (low-level wire error);
facade functions translate Bridge.Error to this type.

- [Hourglass.NamespaceEnsurer](Hourglass.NamespaceEnsurer.md): Boot-time supervisor child that ensures the configured Temporal
namespace exists. Returns `:ignore` from `start_link/0` so no process
is kept around after the check; the supervisor's child-startup
ordering guarantees later children (notably `Hourglass.Subsystem`,
which hosts Workers) don't start until this succeeds.
- [Hourglass.Replay.Mismatch](Hourglass.Replay.Mismatch.md): Returned from `Hourglass.Replayer.replay_history/2` on workflow nondeterminism.
- [Hourglass.Replayer](Hourglass.Replayer.md): Replays a captured workflow history against the current workflow code,
detecting nondeterminism (the workflow producing different commands
than what the original execution produced).
- [Hourglass.Runtime](Hourglass.Runtime.md): One-per-application GenServer holding the CoreRuntime resource.
Workers share the resource via `handle/0`. Constructing more than
one CoreRuntime is wasteful (each spins up its own Tokio runtime).

- [Hourglass.Schema](Hourglass.Schema.md): `use Hourglass.Schema` defines a typed Hourglass payload.
- [Hourglass.Subsystem](Hourglass.Subsystem.md): `:rest_for_one` supervisor wrapping the five Temporal children whose
lifetimes are tied to the bridge-handle registry
- [Hourglass.Telemetry](Hourglass.Telemetry.md): Canonical `:telemetry` events emitted by Hourglass. Attach your own handlers
to project these into your application's audit/event model. See
`Hourglass.Telemetry.LoggerHandler` for an opt-in default.
- [Hourglass.Telemetry.LoggerHandler](Hourglass.Telemetry.LoggerHandler.md): Opt-in default handler that logs every `Hourglass.Telemetry` event. Off by
default; call `attach/0` (e.g. from your application start) to enable.

- [Hourglass.Worker](Hourglass.Worker.md): Per-task-queue Worker — a `GenServer` that owns the bridge-handle
registration for one task queue and runs a small inner Supervisor
hosting the two poll loops driving Temporal Core.
- [Hourglass.Worker.ActivityPollLoop](Hourglass.Worker.ActivityPollLoop.md): Per-Worker Task that drives `BridgeHolder.poll_activity_task/1`
in a tight loop. Each `{:ok, bytes}` is decoded into a
`Coresdk.ActivityTask.ActivityTask` and dispatched directly to
`Hourglass.ActivityExecutor.DynamicSupervisor.start_child/1`
(the shared Application-level executor DynSup).
- [Hourglass.Worker.Supervisor](Hourglass.Worker.Supervisor.md): DynamicSupervisor of per-task-queue `Hourglass.Worker` GenServers.
- [Hourglass.Worker.WorkflowEvaluator](Hourglass.Worker.WorkflowEvaluator.md): Per-activation ephemeral evaluator. Spawned via
`Hourglass.WorkflowEvaluator.DynamicSupervisor`
(`restart: :temporary`) once per workflow activation.
- [Hourglass.Worker.WorkflowPollLoop](Hourglass.Worker.WorkflowPollLoop.md): Per-Worker Task that drives `BridgeHolder.poll_workflow_activation/1`
in a tight loop. On each `{:ok, bytes}` result it dispatches the
activation directly to the shared
`Hourglass.WorkflowEvaluator.DynamicSupervisor`, spawning a
fresh ephemeral evaluator Task per activation. The evaluator runs
once and exits `:normal`; Core handles redelivery on crashes.
- [Hourglass.Worker.WorkflowStateCache](Hourglass.Worker.WorkflowStateCache.md): Per-`(task_queue, run_id)` cache of `Hourglass.Workflow.State` between
activations.
- [Hourglass.Worker.WorkflowTypeResolver](Hourglass.Worker.WorkflowTypeResolver.md): Maps a Temporal Core `WorkflowActivation` to the Elixir workflow
module that should evaluate it.
- [Hourglass.WorkerLauncher](Hourglass.WorkerLauncher.md): Boot-time supervisor child that starts the default Elixir Temporal
worker — the one that polls the `"default"` task queue.
- [Hourglass.WorkerRegistry](Hourglass.WorkerRegistry.md): Registry mapping task-queue names to their Worker GenServer PIDs.
- [Hourglass.Workflow](Hourglass.Workflow.md): Workflow-side API. `use Hourglass.Workflow` declares the module is a
workflow.
- [Hourglass.Workflow.Behaviour](Hourglass.Workflow.Behaviour.md): Callback required by all workflow modules.
- [Hourglass.Workflow.CommandAccumulator](Hourglass.Workflow.CommandAccumulator.md): Process-dict-keyed mutable accumulator that the pure-function evaluator
uses while re-executing a workflow body.
- [Hourglass.Workflow.Evaluator](Hourglass.Workflow.Evaluator.md): Pure recursive evaluator for Hourglass workflows. Per activation
- [Hourglass.Workflow.Info](Hourglass.Workflow.Info.md): Per-activation context the evaluator exposes via
`Hourglass.Workflow.info/0`.
- [Hourglass.Workflow.State](Hourglass.Workflow.State.md): Per-run state threaded through `Hourglass.Workflow.Evaluator.evaluate/3`.
- [Hourglass.WorkflowEvaluator.DynamicSupervisor](Hourglass.WorkflowEvaluator.DynamicSupervisor.md): Application-level shared `DynamicSupervisor` for per-activation
`Hourglass.Worker.WorkflowEvaluator` Tasks.
- [Hourglass.WorkflowHandle](Hourglass.WorkflowHandle.md): Identifier for an in-flight workflow execution.
- [Hourglass.WorkflowStatus](Hourglass.WorkflowStatus.md): Snapshot of a workflow execution's current state. Returned by
`Hourglass.status/2`.

- Exceptions
  - [Hourglass.ActivityError](Hourglass.ActivityError.md): Raised by `execute_activity!/2,3` when an activity fails (after retries).

## Mix Tasks

- [mix hourglass.proto](Mix.Tasks.Hourglass.Proto.md): Regenerate committed protobuf modules from `proto/`.

