Synapsys workers do not accept inbound connections. Everything — every report and\nevery command — rides a single outbound POST the worker makes every few seconds.
\nThat leaves one question: how does the Core tell a worker to do something exactly\nonce?
\n\nSend the desired state, let the worker compare it against what it is doing, and\nact on the difference.
\nif (desiredState != currentState) apply(desiredState);
This replays. A process that takes thirty seconds to stop reports stopping for\nsix consecutive beats, and on each one the desired state still differs from the\ncurrent state, so the command fires again. With a start command it is worse: you\nget six starts.
You can patch around it — suppress commands while a transition is in flight, add a\ngrace period — but every patch is a guess about timing, and timing is exactly what\nan unreliable network takes away from you.
\nThe Core keeps a desiredToken per process and increments it on every user\ncommand. The worker keeps the last token it actually applied, as ackToken,\nand reports it on every heartbeat.
if (desiredToken > ackToken) {
apply(desiredState);
ackToken = desiredToken;
}
Duplicates are now arithmetic rather than judgement. The same response delivered\nsix times applies once, because after the first the tokens are equal.
\nidle had to stop meaning \"stop\". Once a command completes, the Core resets\ndesiredState to idle to mean \"nothing outstanding\". Any client that reads that\nas an instruction shuts down everything it owns. So idle means no command, and\nstop is stopping.
failed cannot be commanded. A state you can be in is not necessarily a state\nyou can be told to enter. Nothing can be instructed to fail, so validity is\nchecked twice — once for what a worker may report, once for what the Core may\nask for.
Order matters at the edges. Update ackToken after applying, never before. A\nclient that acknowledges first and crashes has lost the command, because the Core\nwill consider it done.
Every future starter — Go, Python, whatever comes after — reimplements this loop.\nIt is the one piece of Synapsys that cannot be encapsulated in a library, because\nit is the thing each library independently has to get right.
\nThat is also why Raw API is a first-class connection method rather than a\nfallback: the protocol is the product.
", "url": "https://docs.synapsys.jmzworks.it/blog/2026/08/25/why-tokens", "title": "Why commands are matched by token, not by state", "summary": "The obvious design replays every command. Here is what Synapsys does instead.", "date_modified": "2026-08-25T00:00:00.000Z", "tags": [] } ] }