Skip to content

akter verify

akter verify model-checks the state machine of every actor in an app. It reads each actor’s published contract. It compiles the states, the from to to edges, and the timeout edges into one Quint model. quint verify then checks that model with the Apalache model checker.

Verify an app before you deploy it⁠

  1. Install Java 21 and put it on PATH.
  2. Run akter verify on the app entry.
Terminal
bunx akter verify --entry src/app.layer.ts
  1. If the command exits with code 1, read the actor and the state that each problem line names.
  2. To fix an unreachable state, add a command or job whose to list includes that state, or remove the state.
  3. To fix a dead end, add the state to the actor’s final list. You can also add a command or job that lists the state in from, or a timeout on the state.
  4. Run akter verify again until it exits with code 0.
  5. To block deploys that fail verification, run akter verify in CI before akter deploy.

Problems the verifier reports⁠

  • Unreachable state: No path of edges leads from initial.to to a declared state.
  • Dead end: A reachable state is not in final, and no edge leaves the state. The report prints the Quint trace that reaches the state, one state and the edge that reached it per line.
  • Undeclared state: initial.to, final, a from or to list, or a timeout names a state that the actor does not declare. The verifier skips the Quint check for that actor.
  • Undeclared command: A timeout names a command that the actor does not declare. The verifier skips the Quint check for that actor.

Model inputs⁠

Contract partModel element
statesOne node per state tag.
initial.toThe start node.
Command from and toOne edge from each from state to each to state.
Job from and toOne edge from each from state to each to state.
timeoutsOne edge from the timeout’s state to each to state of its command.
finalThe states that may have no way out.

Queries add no edges, because a query never changes state. The verifier reads the published contract only, so it never runs a handler.

Timeout edges⁠

A timeout is an edge of its own kind in the state graph and in the Quint model.

  • Edge: A timeout on state S that runs command C adds one edge from S to each state in the to list of C.
  • Label: The Quint model labels the edge timeout <command>. A trace line reads Archived, by timeout archiveIdle.
  • Reachability: A state that only a timeout edge leads to is reachable.
  • Dead ends: A state whose only exit is a timeout is not a dead end.
  • Input: The verifier reads state and command from each entry of the actor’s published timeouts list. It ignores afterMs, because a delay never changes which states a path visits.

The published contract lists timeouts only when the actor declares one. An actor without timeouts gets no timeout edges.

Output and exit codes⁠

  • Report: The command prints one line per actor, either <Actor>: ok or <Actor>: <n> problems followed by one line per problem. A summary line ends the report.
  • Exit code: The command exits with code 0 when no actor has a problem. It exits with code 1 when any actor has a problem.
  • Requirements: quint verify needs Java 21 on PATH. The first run downloads Apalache into ~/.quint.

Why the verifier checks declared edges⁠

A command’s from and to lists are part of its contract. The engine refuses any transition outside those lists, so the declared edges bound every path an actor can take. A proof over the declared edges holds for every handler that typechecks.

Apalache checks traces up to a fixed number of steps. akter verify sets that bound to the number of declared states. A shortest path through N states takes at most N - 1 steps, so the bound covers every reachable state and every reachable dead end.

An unreachable state is dead code in the contract. A dead end that final does not list is an actor that can stop accepting commands without a declared reason. Actor grammar describes final and the other slots.