Stephanie Jarmak

Temporal case study · Code

Complete annotated source

Eight annotated files show the pre-Temporal controller and recovery path, and the Workflow, Activity, bridge, and Worker code that replaced them, with the complete test matrix beneath.

Each reader renders the complete source with IDE-style syntax colors. Select a line section to open its explanation directly beneath the code, or download the raw file from the reader. The before excerpts cite and link the exact public upstream revision they abridge.

  1. 01

    Before Temporal

    city_runtime_excerpt.go

    A readable abridgment of the production tick that repaired orphaned assignments, reconciled sessions, delivered nudges, and ran a second wake-up backstop.

    Open annotated source
  2. 02

    Before Temporal

    session_recovery_excerpt.go

    A readable abridgment of the production close-and-release path used to recover work after a session disappeared.

    Open annotated source
  3. 03

    After Temporal

    bridge.go

    Delivers a durable work-store event through Signal-With-Start, then records the exact Workflow receipt.

    Open annotated source
  4. 04

    After Temporal

    workflow.go

    Owns deterministic progression for one work item, including duplicate delivery, a finite-run seal, cancellation, and formula visibility.

    Open annotated source
  5. 05

    After Temporal

    outcome_workflow.go

    Keeps a verified result visible and retrying until the coordinator records a disposition and acknowledges the exact delivery fence.

    Open annotated source
  6. 06

    After Temporal

    activity.go

    Claims the exact work generation, starts or reattaches the bound agent, heartbeats progress, propagates cancellation, and fences completion.

    Open annotated source
  7. 07

    After Temporal

    command_agent_executor.go

    Invokes a trusted executable through a bounded JSON/JSONL protocol that supports resolve, execute, progress, result, and cancellation.

    Open annotated source
  8. 08

    After Temporal

    workers.go

    Registers orchestration and agent execution on separate Task Queues, with a fail-closed shadow worker for deployment.

    Open annotated source

The full test matrix

The suite runs with one command: cd services/temporal-maintenance && go test -race ./.... The package that implements the Temporal and Beads boundary carries 18 Go test files. Every case below runs unconditionally; a small number of heavier integration tests require a local Temporal development server and skip themselves when the Temporal CLI is not available. The article names five invariants; the table holds those down and adds the Continue-As-New boundary. The named cases are here.

What has to hold Where it is asserted
Workflow behavior workflow_test.go: cases covering duplicate ready delivery, malformed events, event-limit rejection, and seal enforcement
Activity behavior activity_test.go: cases covering fenced claims, heartbeating, stale-generation rejection, and artifact bounds
A duplicate Signal schedules only one Activity TestWorkflowDuplicateReadyDeliverySchedulesOneActivity Delivers the same ready event twice and requires the Workflow to schedule the agent Activity once. Redelivery is expected on this path, so it has to be harmless.
TestCoordinatorOutcomeWorkflowDeduplicatesReadySignal The same property on the delivery side: a repeated OutcomeReady signal must not open a second delivery loop for one result.
A stale acknowledgement fails closed TestCoordinatorOutcomeActivityFailsClosedAtAcknowledgementBoundary An acknowledgement that no longer matches the current store, work item, outcome, generation, and session is refused rather than accepted.
TestActivityCancellationReachesAttachedSessionAndStaleCompletionFails Cancels an Activity that already has an agent attached, then has that agent present a stale claim token. One terminal receipt is written and the stale completion fails closed.
Cancellation reaches the agent without leaving the Workflow hanging TestWorkflowCancellationDoesNotHangWhileActivityStops Cancellation while the agent is still stopping. The Workflow has to finish rather than wait on a process that is on its way out.
TestActivityCancellationBeforeFirstCheckpointUsesResolvedSession The harder arm: nothing has been checkpointed yet, so the Activity has to ask the resolver which session it owns instead of reading heartbeat details.
Continue-As-New preserves state and receipts TestCoordinatorOutcomeWorkflowContinuesAsNewWithStateAndCounters Continue-As-New starts a fresh Event History for a long-running Workflow. Redelivery state and counters have to cross that boundary intact.
TestCoordinatorOutcomeWorkflowDoesNotLoseAcknowledgementAtHistoryBoundary The failure that boundary invites: an acknowledgement arriving exactly as the history rolls over must not be dropped.
Captured histories still replay, and incompatible code fails the gate TestReplayPersistedWorkflowHistory Runs current Workflow code against captured histories and requires the same decisions. This is the check that catches a nondeterministic change before it ships. and TestReplayRejectsPlantedNondeterministicWorkflow The negative case. A deliberately nondeterministic Workflow is planted and replay must reject it, which is what proves the gate is wired up at all. in failure_matrix_test.go
A killed Worker resumes without creating a second agent session TestActivityWorkerCrashResumesFromHeartbeatWithoutSecondSession Kills the Worker after the agent is running and a heartbeat checkpoint exists, then requires the retry to resume from that checkpoint against the same session. covers failure after the agent is running; TestActivityCancellationBeforeFirstCheckpointUsesResolvedSession The same case from the other side: with no checkpoint recorded, the retry must resolve the running session by identity rather than start a second one. covers failure before the first heartbeat