Skip to content

Use case: actor state store (FSM actors rebuilt from a central log) #36

Closed

Description

@adityamukho

Summary

Add a use case to content/developer-tooling-ideas.md: Minigraf as the state store for actors, with a focus on finite state machine (FSM) actors.

This is an idea, not a shipped tool. The goal is to describe it well enough that someone else could build it.

The idea

Each actor owns one Minigraf file. The actor is the only writer. Its state is a graph that other actors, tools and people can query, not an opaque blob inside the actor.

For distributed actors, a central durable log (for example Kafka, partitioned by actor ID) is the source of truth. Each actor's file is a local view that can be thrown away and rebuilt from the log at any time. Minigraf needs no replication or merge for this.

For FSM actors, most of the logic can live in the graph as data:

  • The FSM definition: states and transitions are facts (:from, :to, :on, guard).
  • Current state: the latest state fact. History comes free.
  • Guards: Datalog rules over the actor's facts. not-join covers "no open dispute" style checks.
  • Enabled transitions: one rule joins the current state, the incoming message and the guards.
  • Derived state: counters, totals, time in state, retry counts, from aggregates and window functions.
  • Invariants: rules that should always return nothing, checked after each transaction.
  • Timeouts: deadlines as valid time; a rule finds actors past their deadline.

Side effects stay in code. The graph names the action (:action :send-reminder), and a small table in host code maps each name to a function. The actor becomes a generic loop: receive, transact the message as facts, query enabled transitions, pick one, transact the new state, run the named action.

Why Minigraf fits

  • Single writer: Minigraf allows one writer at a time. An actor handles one message at a time. They match.
  • One file per unit: one actor per file fits the <1M fact ceiling and the one-file-per-unit model.
  • Crash and restart: supervisors restart failed actors, and Minigraf replays its WAL on open.
  • Queryable state: other actors read with a shared handle. No ask messages, no waiting in the mailbox.
  • Time travel without replay: "what did this actor know at time T?" is one :as-of query, not a replay into a new instance.
  • Late messages: valid time records when an event happened, transaction time when the actor learned it. A late correction updates the past and keeps the old belief.
  • FSM audit: "which message moved this actor from :pending to :approved?" and "what state was it in when message M arrived?" need no extra logging.

What it fixes in existing frameworks

Event sourcing with snapshots already exists (Akka Persistence, Orleans JournaledGrain, Proto.Actor). The gains are elsewhere:

  • Code changes no longer break replay. If the log holds raw facts, rebuild copies facts and runs no actor code. The v3 log writers that import raw facts make this possible, and they keep the original transaction time.
  • Two common complaints about actors are hidden state and hard debugging. Queryable, bi-temporal state addresses both.
  • What-if checks: change a guard rule, then run it against past :as-of states to see which transitions would now go another way.
  • Impact before deploy: query every actor for "in :retrying right now" before changing that logic.
  • Code version as a fact: tag each transaction with the code version, then ask which decisions version 1.4 made.

What still needs work: the meaning of old facts after a rename or state split (fix with correcting facts or mapping rules), and versioned message formats for messages in flight.

Link to decision telemetry (#26)

The graph records decisions in the declarative FSM layer. Decision telemetry covers the parts that stay as code (actions, message parsing, hot paths). Shared transaction and message IDs join the two, and a causation ID on each message follows a decision chain across actors. Keep telemetry in a separate file per run, not in the actor's state graph or the central log.

How someone could build it

  • Prototype in Rust with Ractor or Kameo, single node, no FFI.
  • Keep the core runtime-free: two operations, "find enabled transitions" and "commit this transition with its log offset". Thin adapters per runtime.
  • JVM: Apache Pekko has cluster sharding, passivation, persistence with a pluggable journal, and an FSM style. Vert.x lacks sharding, so the hardest part would be custom. Uses minigraf-jvm.
  • Python / agents: Ray named actors, using the Tier 1 Python binding.
  • Store the last applied log offset as a fact in the same transaction, for resume and exactly-once apply.

Limits to state in the doc

  • Blocking API: calls block and fsync. Use spawn_blocking, a worker thread or a worker verticle. Never hold a WriteTransaction across .await.
  • Batch writes: drain the mailbox into one WriteTransaction, or use SyncMode::Normal where a rerun is safe.
  • Speed: a Datalog query is slower than a struct field read. Keep hot-path state in memory.
  • Many tiny actors: millions of short-lived actors means millions of files. Use in-memory databases or skip it.
  • Queries across actors need fan-out. A global view belongs in a different store fed from the same log.
  • Log retention: log compaction destroys history. Use unlimited retention or tiered storage.
  • Deterministic IDs: rebuilds must produce the same entity IDs.
  • Rule persistence is still at the design stage (Rule persistence: deeper design consideration minigraf#241). Until then, the actor registers its rules on every open.
  • Conflicting transitions need a priority rule. A "why not" view for failed guards would help debugging (see the query profiler, post-1.0: build query profiler minigraf#185).

Suggested content

  • The idea: one actor, one file, one writer, rebuildable from a central log
  • A fact schema for an FSM actor (state, transition, guard, message, action, log offset, code version)
  • An "enabled transitions" rule with a not-join guard
  • An :as-of query: what state was the actor in when message M arrived?
  • An invariant rule that should return nothing
  • The generic actor loop, as a short sketch
  • Limits, including the blocking API and per-actor file count
  • A link to the decision telemetry section
  • A clear note that this is an idea for others to build, with no official tool

Related


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions