Bundle contract for a durable Docket backend.
A backend is the configuration and substitution boundary. It supplies semantic lifecycle transitions plus focused graph, run, and event capabilities. Store modules remain independently testable, but callers must not assemble capabilities from unrelated backends.
Lifecycle writes use Docket.Backend.TransitionStore. Every backend
declares that capability explicitly through capabilities/0 and resolves
its implementation through transitions/0; contract negotiation rejects
backends that do not. Backend-native transactions are private
implementation details and never cross this contract.
The backend also owns its supervision entry point. child_spec/2 receives
the options nested under {BackendModule, options}, the small set of
runtime-owned policies needed for execution, and the runtime-generated name.
The already-resolved opaque context remains a separate argument. The callback
returns the single child specification the host places in its supervision
tree.
Testing execution is also explicit. drain_runs/2 receives the same resolved
context separately; :manual instances invoke it only through the public
drain operation, while :inline instances invoke it after committed work is
scheduled. Backends return a summary containing :limit_reached.
Summary
Types
A module implementing one of Docket's focused store contracts.
Opaque backend context passed through without interpretation by core.
Scope that determines graph/run ownership; tenant identifiers are non-empty.
Authorization and tenancy scope for a run or its events.
Callbacks
Declares the backend contract and semantic transition capability.
Builds the backend's supervision child specification from options and its resolved context.
Resolves the opaque root context passed to the backend's stores and transition store.
Synchronously claims and drains due runs using the resolved backend context.
Returns the backend's Docket.Backend.EventStore implementation.
Returns the backend's Docket.Backend.GraphStore implementation.
Returns the backend's Docket.Backend.RunStore implementation.
Returns the backend's Docket.Backend.TransitionStore implementation.
Types
@type capabilities() :: %{ contract_version: 2, transitions: %{:version => pos_integer(), optional(atom()) => term()} }
@type capability() :: module()
A module implementing one of Docket's focused store contracts.
@type ctx() :: term()
Opaque backend context passed through without interpretation by core.
@type owner_scope() :: :tenantless | {:tenant, String.t()}
Scope that determines graph/run ownership; tenant identifiers are non-empty.
@type scope() :: :system | :tenantless | {:tenant, String.t()}
Authorization and tenancy scope for a run or its events.
Callbacks
@callback capabilities() :: capabilities()
Declares the backend contract and semantic transition capability.
Version 2 requires transitions/0, transition version 1, and a module that
implements every Docket.Backend.TransitionStore callback. Contract
negotiation rejects a backend that omits this callback or declares any
other contract shape.
@callback child_spec(opts :: keyword(), ctx()) :: Supervisor.child_spec()
Builds the backend's supervision child specification from options and its resolved context.
Resolves the opaque root context passed to the backend's stores and transition store.
@callback drain_runs(ctx(), opts :: keyword()) :: {:ok, drain_summary()} | {:error, term()}
Synchronously claims and drains due runs using the resolved backend context.
@callback events() :: capability()
Returns the backend's Docket.Backend.EventStore implementation.
@callback graphs() :: capability()
Returns the backend's Docket.Backend.GraphStore implementation.
@callback runs() :: capability()
Returns the backend's Docket.Backend.RunStore implementation.
@callback transitions() :: capability()
Returns the backend's Docket.Backend.TransitionStore implementation.