Architecture

The state machine performs no I/O, so it names the side effect and the caller — which owns the transaction, the repositories and the outbox — carries it out. That is what makes the rule set reviewable as a table.

FccActivationTransitionService is the single bean that applies both machines' decisions, and it is @Transactional(propagation = MANDATORY): the watchdog’s callers claim their rows with FOR UPDATE SKIP LOCKED, whose locks live until the claiming transaction commits, so a nested or new transaction here would apply the transition outside the scope that holds the claim. MANDATORY turns "somebody forgot the transaction" into a call-site failure instead of a race nobody reproduces.

This is the specification, reproduced from FccTestStateMachine’s class Javadoc. Anything not listed is `Denied.

Four rows are load-bearing and easy to "fix" wrongly:

Stopping a paused campaign carries CLEAR_SCHEDULED_AT only, because a pause leaves nothing on the ACS to stop. FccStopService.stop runs the identical code for a stop and a pause, so by the time a campaign is PAUSED every activation of its live run has either been closed locally (PLANNED — nothing was ever sent for it) or been sent a real STOP and moved to STOPPING, and every PLANNED reactivation has been closed with it. STOPPING is deliberately not in FccStopService.LIVE_STATES: that run is draining under ft.fcc.stop-grace with its STOP already on the ACS, and a second command would burn a command sequence to repeat an instruction that is being carried out. Nothing can re-open the gap either — SCHEDULE_DUE and REACTIVATION_DUE are denied from PAUSED, and an ACTIVATE_* that would create a new run leaves PAUSED in the same transaction — so the only thing this stop can still have to do is clear a pending instant. Declaring the other effect would be the table claiming that a paused campaign may own something live on the ACS when it may not.

Neither effect is what performs the run half, which is why this is a question about the specification rather than about behaviour: FccStopService queries fcc_activation unconditionally instead of gating on STOP_ACTIVE_ACTIVATION, so an exotic live row would be closed either way.

One consequence is load-bearing: the draining run keeps stop_reason = USER_PAUSE, because the stop finds nothing to re-stamp. That is what isUserInitiatedStop reads, so when the run finally drains, the ACTIVATION_STOPPED the ACS reports is still not fed to the campaign and a stopped-after-pause campaign cannot slide from NOT_ACTIVE into STOPPED — this product’s word for "the ACS stopped it and nobody asked".

SCHEDULED_FOR_REACTIVATION + ACTIVATE_IMMEDIATELY carries STOP_ACTIVE_ACTIVATION as well as CLEAR_SCHEDULED_AT, and that second effect is not tidiness. A campaign between daily runs already owns its next one as a PLANNED row, and the operator is asking for a different run right now. Leaving the old row behind orphans it permanently: the campaign moves to RUNNING, so FccActivationHandler.dispatch then evaluates RUNNING + REACTIVATION_DUE, is denied, and leaves the row PLANNED — which the reactivation poller re-claims every tick for the rest of the installation’s life, gaining one more orphan on every later PLAN_REACTIVATION. A row that had already reached DISPATCHING or RUNNING is worse: it stays live on the ACS and keeps measuring under a campaign that has moved to a different run.

FccActivationHandler.stopSupersededRun performs it, and delegates to FccStopService.stopLiveRun rather than reimplementing the stop, because the two cases a superseded run splits into are exactly the two that service already distinguishes: a PLANNED row is closed locally with no command — nothing was ever sent for it — while a DISPATCHING/RUNNING one takes the normal STOP_REQUESTED path with a STOP for the ACS. A second implementation of that split is a second chance to send the ACS a STOP for a run it has never heard of.

Two details of it are load-bearing:

This edge closes a bean cycle — FccActivationHandler → FccStopService → FccActivationTransitionService → FccReactivationService → FccActivationHandler — so FccStopService is injected into the handler as an ObjectProvider and resolved per call rather than at construction. The last edge is the one that cannot move: planning the next daily run is the handler’s job. FccResultDeadLetterService breaks its own cycle with the ingest service the same way, for the same reason.

ARCHIVED is unreachable in both directions. It is written only by the M4 legacy ETL, for campaigns that finished years ago in the legacy product and must never be re-run, re-scheduled or reported on as live. Nothing leads to it and nothing leads out of it; an event naming it is a bug in the caller and is denied like any other.

Reproduced from FccActivationStateMachine’s class Javadoc. A dash in the Stop reason column means `null, which means leave stop_reason as it is — not "clear it".

Four rows carry reasoning that is not obvious from the table:

The one place a caller deliberately diverges from this table is a PLANNED run being stopped. PLANNED means no command was ever sent — FccActivationHandler.dispatch writes the ACTIVATE and moves the row to DISPATCHING in the same transaction, which is also why a planned run’s command_seq is still the unassigned placeholder 0. Following PLANNED + STOP_REQUESTED → STOPPING would send the ACS a STOP for a run it has never heard of: it would consume a command sequence, it would be answered as an unknown activation, and the run would sit in STOPPING until the stop grace expired. FccStopService.closePlannedRun therefore closes it locally as STOPPED with no command at all, and the endpoint answers commandPublished: false — see POST /FCC/stop. The code marks this as an acknowledged follow-up: a dedicated PLANNED + CANCEL → STOPPED event carrying SET_STOPPED_AT, SET_FINISHED_AT and no PUBLISH_STOP_COMMAND would say the same thing in the one place that is meant to hold transition rules.

Every poller in this service is two beans, and the split is the same in all five. A @Component carrying the @Scheduled method holds no transaction and no business logic; a second @Component carries the @Transactional method that claims and applies. FccActivationScheduler / FccActivationSchedulingService and FccActivationWatchdog / FccActivationClosingService follow the shape FccOutboxDispatcher / FccOutboxPublisher established in M1.

Two independent reasons, and either one alone would be enough:

The transactional bean therefore claims and applies in one scope, and each pass is its own transaction: a backlog of due campaigns and a backlog of due reactivations are independent, and one failing has no reason to discard the other’s work.

Inside a pass, a failure re-throws rather than being caught per row — FccActivationSchedulingService.startDueScheduledTests says so explicitly. FccActivationHandler.activate is @Transactional on another bean and therefore joins this transaction, and Spring marks a participating transaction rollback-only the moment the inner proxy sees an exception. Catching and continuing would start further campaigns, log them as started, and then have the commit throw UnexpectedRollbackException and discard all of them — a log that says a campaign started and a database that says it never did. Re-throwing keeps the tick honest: nothing was applied, nothing is claimed any more, and the rows are simply claimed again next tick.