FLUXFLUX
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • Introduction
  • Quickstart
  • From Your Data to a Synthetic Copy
  • Two Specs, One Substrate
  • The Six Families
  • The FLUID Seam
  • Deterministic & Governed
  • Runtime & Evidence
  • Anatomy
  • The Nineteen Kinds
  • Versions
  • Changelog
  • JSON Schema 0.5.4
  • UI Hints 0.5.4
  • Enforcement Contract 0.5.0
  • Bundle Manifest 0.5.0
  • Overview
  • Tutorial
  • How-to guides
  • Reference
  • Explanation
  • Command line
  • Error codes
  • Accuracy program
  • The vNext Plan
  • The Nine RFCs
  • Playback Source (proposed)
  • Conformance Profiles
Examples
What's New
FLUID
GitHub
  • FLUX Simulation Engine
  • Tutorial
    • First evidence pack in five minutes
  • How-to guides
    • Model your customers
    • Add a journey
    • Use the FLUID seam
    • Calibrate from aggregates: declare a scorecard
    • Draw a column given another
    • Ship with evidence
    • Write a bundle from a profile
    • Score a run against a profile, in full or sampled
    • Seal and score a prediction
    • Load a simulation into a database
  • Reference
    • Command line
      • fluxsim init
      • fluxsim validate
      • fluxsim plan
      • fluxsim apply
      • fluxsim run
      • fluxsim verify
      • fluxsim ship
      • fluxsim replay
      • fluxsim calibrate
      • fluxsim accuracy
      • fluxsim gate
      • fluxsim expr
      • fluxsim describe
      • fluxsim plugins
      • fluxsim explain
    • Error codes
    • Python API
    • Schemas
    • Specifications
      • FLUX Simulation Engine: kernel normative specification (v0.1)
      • FLUX Simulation Engine: kernel v2 normative specification (v0.2)
      • Seam generator and fidelity check: normative specification (v0.1)
      • Profile document: normative specification (format 1-1-0)
      • Scorecard: normative specification (format 1-1-0)
      • Sample-based verification: normative specification
      • Parameter register: normative specification (format 1-1-0)
      • flux-expr/1: normative specification (v0.1)
      • flux-expr/2: normative specification (v0.1)
      • flux-expr/3: normative specification (v0.1)
  • Explanation
    • Architecture and patterns
    • The six-step loop
    • Determinism and the seed tree
    • The FLUID seam
    • The evidence pack, and what it does not claim
  • Accuracy program

    • The accuracy program: design
    • Accuracy report

ADR 0001: diverge from Mesa for the simulation substrate

Status

Accepted

Context

Mesa 3 (Apache-2.0, JOSS 2025, roughly 3.8k GitHub stars) is the standard Python agent-based-modeling framework: Model(rng=...), a batch_run helper with seed control, grids, and a visualization layer. Borrow-before-build search: "agent-based modeling python 3 deterministic seed batch_run" (2026-09-06); fetched https://github.com/projectmesa/mesa.

FLUX's kernel needs a contract-bound, byte-stable, seed-tree scheduler: every decision (cohort allocation, trait draw, signal, detection, transition, delivery/suppression, assignment, emit) must be reproducible byte-for-byte from a seed, hashed into a run digest, and free of any floating-point accumulation path. That is a narrow, closed vocabulary of a few hundred lines -- not a general research harness.

Decision

Do not depend on Mesa. Write the scheduler, clock, and seed tree directly in flux_engine.core / flux_engine.world / flux_engine.runtime.

Consequences

  • No grid/visualization/general-ABM surface to fight or route around.
  • The scheduler's total-order key and the seed tree's derivation function are flux_engine-specific and fully within this project's own test and digest-stability guarantees, rather than inherited from a library whose primary users are researchers plotting agent trajectories.
  • The cost is writing (and testing) a scheduler ourselves. Given the target is a closed vocabulary of a few hundred lines, this is judged cheaper than adapting Mesa's Model/Agent/Scheduler classes to a determinism contract they were never designed to hold.
Last Updated: 11/19/26, 8:45 AM