43. Sealed types for the internal job state
Date: 2026-10-14
Status
Accepted
Context
The implementation in org.bikesched.internal carried the state of claimed jobs, steps and
attempts as strings, nullable columns and boolean flags. A claimed job had failingState,
failureAttempts, compensatedState, parentJobId, recurrence and fixedRateAt, whose valid
combinations only the processor knew; step rows compared kind and state strings; store results
such as PollStep or EventWait were one record with a state string and fields valid only in
some states; JobAttempt tracked its lifecycle with three booleans. Every reader re-derived the
cases with if chains, and a missing case compiled.
DefaultJob also mixed two modes in each step primitive: running a handler and replaying it to
collect the compensations of a job claimed to be compensated.
Decision
bikesched models these cases as types the compiler checks:
JobPhase(Run,Compensate,HandleFailure) is what a claim is for,JobOrigin(OneOff,Child,Occurrence) where the job came from. The store maps the columns once, when claiming.ClaimEndcarries the job, its lock and aFollowUp(None,NotifyParent,ScheduleNext) that the ending write performs in its transaction.- Store results with distinct outcomes are sealed interfaces (
ChildWait,PollStep,EventWaitResult); step kinds and states are the enumsStepKindandStepState, job states the publicJobState. JobProcessorswitches over a sealedVerdictof an attempt and its recorded outcome;JobAttempthas one state enum.CompensationReplayholds the replaying variant of every step primitive;DefaultJobdelegates to it when the claim’s phase isCompensate.
The schema is unchanged: the types are mapped from and to the existing columns.
Consequences
- Exhaustive
switchstatements replaceifchains; a new phase, origin, follow-up or store outcome fails to compile until every reader handles it. - Fields exist only where they are valid, so nothing reads a
nullthat means “not this case”. - Writes that end a claim take a
ClaimEnd, so ending a child job or an occurrence of a recurring job cannot forget its follow-up. - Store tests compare the typed results instead of strings.