Changelog#

All notable changes to this project are listed here. Versions follow semantic versioning; while the major version is 0, minor versions may change behavior.

[Unreleased]#

Nothing yet.

[1.0.0]#

The first stable release. The playground writes, runs, checks and reports on distributed algorithms, and the repository around it is set up to keep it that way.

Added#

• Eighteen algorithms with the properties they must satisfy, from flooding and reliable broadcast to logical clocks, the Chandy-Lamport snapshot, a majority-quorum register, total order broadcast, Paxos and Ben-Or.
• Properties written next to the algorithm and checked after every step, with the instant and the process of the first violation.
• Batch runs over many seeds in background workers, fault schedules drawn by count or by rate, shrinking of a failing schedule to what is necessary, and a behaviour profile over a grid of fault conditions, exportable as a Markdown report.
• A suite that travels with the scenario: seeds, generated faults and their window are saved in the JSON, so dsp run scenario.json --suite is a one-line check in continuous integration.
• Writing help in the editor: completion built from the parse tree and quick fixes that declare a variable, add a missing handler or add a module from the library.
• The command line as an npm package: npx distributed-systems-playground profile scenario.json.
• An About button with the project, its author and the running version.
• An accessibility suite: names of every control, landmarks, keyboard focus, dialogs and colour contrast in both themes.
• Three badges that say something: how many algorithms ship, how many properties they declare and how many documentation pages there are, each checked against the repository by the test suite.
• Dependabot for the workflow actions and the pinned Playwright of the browser suites, with test/browser/requirements.txt pinning that version.
• Commit message checks with scripts/check-commits.mjs, on pull requests and, with npm run hooks, locally as you write them, alongside a pre-push hook that runs the Node tests.
• A release workflow: a tag runs the tests, refuses to ship when the tag, package.json and the changelog disagree, and publishes the notes already written in the changelog.

Changed#

• The diagram generator refuses to write a picture whose labels leave the frame, and the closing line wraps when the reason and the cost do not fit side by side.
• Every example opens with a schematic of its protocol: roles as lifelines, phases down the side, labelled messages, and the sentence that says why it works. The eighteen descriptions live in scripts/protocols.cjs, apart from the code that draws them.
• Four diagrams explain the project where words were doing the work alone: how a run is produced, how the pieces fit together, the layers a message goes through, and the loop from a question to the fault that answers it. They are drawn by scripts/make-diagrams.mjs in a light and a dark version, and npm run check fails if one is out of date.
• The README is a quarter of its former size: what a reader needs before deciding to try the project, with everything that duplicated the documentation pointing at it instead. Two pages were added for the material that only lived there: A guided tour and Questions, related tools and references.
• The specification reports the status of the current implementation rather than of version 0.5, and a guard test keeps that appendix from drifting again.
• .gitattributes marks index.html and manual/ as generated, so reviews collapse them and the language statistics stay honest; .editorconfig and CODEOWNERS complete the setup.

Fixed#

• Playwright is pinned to 1.63.0 and the workflow actions to v7 (checkout, setup-node, setup-python), the versions Dependabot proposed and the tags confirm.
• The screenshots, the animations and the social preview show the current interface, in the dark theme the rest of the material uses. The card of the social preview shows the tool at work — the graph and the space-time diagram — rather than the table of one algorithm.
• The commit message checker reads a range again: it asked git to separate its output with -z instead of passing a NUL byte inside an argument, which Node refuses.
• The fault suite looks for a cursor position inside the pause instead of assuming one, which differs between browser engines.
• The touch and layout suites run on Firefox as well: the mobile-context option it does not support is dropped there, keeping the viewport and the touch support.
• The export box and the space-time diagram carry a description for assistive technology.
• The command line no longer fails when its output is closed early, as | head does.

[0.23.0]#

Added#

• Ben-Or randomized consensus, with agreement, validity and termination as properties. The decided value and the number of rounds change with the seed, which is what a randomized algorithm looks like: it terminates with probability one, not within a bound.

[0.22.0]#

Added#

• Single-value Paxos with two competing proposers, with agreement, validity and termination as properties. Its behaviour profile keeps agreement and validity under every fault condition and loses termination with the majority.
• New gallery category: Consensus now also covers Paxos.

[0.21.0]#

Added#

• Total order broadcast with a sequencer, with the prefix property (what one process delivered is a prefix of what any other delivered) and delivery of everything as properties. Crashing the sequencer keeps the order and stops progress; delivering without waiting for the order breaks the property at once.

[0.20.0]#

Added#

• Majority-quorum register (read and write with a write-back phase), with validity of reads and termination of operations as properties, and a replica state that survives a recovery. Its behaviour profile shows safety holding under every fault condition and liveness falling with the majority.
• New gallery category: Replication.

[0.19.0]#

Added#

• Two algorithms from the catalog: logical clocks (Lamport and vector, with the invariant that nobody knows more about a process than the process itself) and the Chandy-Lamport snapshot on FIFO channels (with conservation of the recorded cut).
• New gallery categories: Logical time and Global state.
• Example scenarios can override fields of their timing preset, which the snapshot uses to require FIFO channels.

[0.18.0]#

Added#

• Contextual completion in the editor, built from the parse tree: instances inside ⟨ … ⟩, then the events of that instance's interface with their arity, and elsewhere state variables, parameters, functions, built-ins and keywords. Ctrl + Space opens it anywhere; while an algorithm is half-written its instances are read from the header.
• Quick fixes on diagnostics: declare an undeclared variable in state, add a handler for an unhandled indication with its arguments, add a module that implements a missing interface, or declare the interface.
• SimCore.builtinIfaces(), so that the editor knows the events of Net and Rounds.

[0.17.1]#

Changed#

• The behaviour profile now reads as a summary: every condition carries a verdict (held, held with fewer processes reporting, broken), a sentence states what the algorithm holds under and what breaks it, the reach is shown as a bar in the page, and the table scrolls inside the panel instead of stretching it.

[0.17.0]#

Added#

• Behaviour profile: the same algorithm run over a grid of fault conditions (no faults, crashes, crash and recovery, pause, partition, overlapping partitions, link failures, omissions, a zone), with how often each property held, messages, reach, median settling time and a failing seed to open. Available as Behaviour profile in the Scenario tab and as dsp profile.

[0.16.0]#

Added#

• Fault plans accept rates: crash:0.5/s makes faults arrive as a Poisson process over the window, with durations drawn from an exponential distribution, so every run gets a different schedule. Numbers and rates can be combined.

Changed#

• Durations of generated interval faults come from an exponential distribution instead of a uniform one, with a floor of 15% of the window; generated schedules are returned in time order, and a generated recovery always falls inside the window.

[0.15.0]#

Added#

• Faults armed by a condition: any fault can wait for a boolean expression over the state of every process, written like a property, and fire the first moment it holds, lasting for the duration given in For.
• One-way partitions: only the messages leaving the first group are dropped.
• zone:1 in fault plans: about a third of the processes crash at the same instant.
• SimCore.parseExpression, for a single expression such as a fault condition.

[0.14.0]#

Added#

• Draw and Redraw in the Scenario tab: a random fault schedule for the run in front of you, of the kinds and within the window you name. The drawn faults become ordinary faults of the scenario, so they can be run, watched, edited and exported.

[0.13.1]#

Changed#

• The layer-color check no longer assumes that packets are in flight at one fixed instant: it looks for a moment when they are, which differs between browser engines. The gallery check no longer hardcodes the number of examples.

[0.13.0]#

Added#

• Four algorithms from the catalog, each with the properties it must satisfy: perfect failure detector (P) under timed synchrony, eventual leader election (Ω) under partial synchrony, Ricart-Agrawala mutual exclusion, and two-phase commit with its blocking scenario.
• New gallery categories: Coordination and Leader election.

Changed#

• The README opens the algorithms it can run, with the properties each one checks; the keyboard shortcuts moved to the interface guide.
• Termination properties are written as "every correct process decided", so that a process crashing after deciding no longer breaks them.

[0.12.0]#

Added#

• Shrinking of a counterexample: a generated schedule that breaks a property is reduced to the faults that still produce the same failure, then shortened. Available as minimize next to a failing seed in the Scenario tab, and as --minimize on the command line.

[0.11.2]#

Security#

• The version check compares plain strings instead of building a regular expression from the version number, which only escaped dots. A guard test now fails if any regular expression is built from data.

[0.11.1]#

Security#

• No HTML is matched with regular expressions any more, anywhere: the build checks each source before inlining it, the documentation generator escapes inline markup and reads text by walking it, and the tests scan the template and the markdown instead of stripping tags. A guard test fails if a regular expression starts matching tags again.

[0.11.0]#

Added#

• Generated fault schedules for batch runs: crash, recover, pause, partition, link and omission, each drawn from the seed of its run, in the Scenario tab (Faults per run and Window) and on the command line (--faults, --fault-window).
• The schedule of a run that had a problem is shown with its seed, and opening that seed adds exactly those faults to the scenario.

[0.10.2]#

Changed#

• The batch suite no longer depends on how fast the machine is: it stops a batch in the same tick it starts one, waits longer for results, and allows a loaded machine to answer more slowly.

[0.10.1]#

Fixed#

• Leaving full screen now leaves presentation mode as well. On browsers that handle Esc themselves, the mode stayed on with the controls hidden.

Changed#

• The browser suites print the checks that already passed when a step throws, and touch skips the gesture checks outside Chromium, where a CDP session is not available.

[0.10.0]#

Added#

• Run over many seeds in the Scenario tab: the same scenario runs in background workers, one run per seed, reporting per-property results and the first seed that broke each one; clicking a seed opens that run. Falls back to running on the page, one seed at a time, where workers are not allowed.
• The browser suites can run on Firefox and WebKit with DSP_BROWSER, and CI runs all three engines on the main branch.
• A browser suite for batch runs.

[0.9.2]#

Changed#

• The interface source is split into thirteen files under src/ui/, one per area, concatenated into a single scope at build time. The build now also fails when the bundled script does not parse.

[0.9.1]#

Added#

• The browser suites live in test/browser/ and run with npm run test:browser: 233 checks over controls, library, settings, properties, faults, security, touch, layouts and playback speed. A separate CI job runs them on every push.
• Guard tests: no assignment of data to innerHTML, no eval, no markup cleaned up with regular expressions, external JSON parsed without keys that reach a prototype.
• A test that the version is the same in package.json and CITATION.cff and has a changelog entry.
• A test that the numbers quoted in the documentation still match what the engine produces.
• Fuzzing of the parser and the checker over three thousand malformed programs.
• A test that the interface is fully translated, blocks included.

[0.9.0]#

Added#

• One-way link failures: only the messages from the first process to the second are lost.
• Process pauses: a process handles nothing for an interval, then handles everything that queued up, with its state intact.
• Omission faults: a process drops a share of the messages it sends, receives, or both, without crashing.
• Pause here on a selected process, next to the other fault buttons, and the new fault types in the Scenario form.
• Pauses are drawn on the graph and on the space-time diagram, and reported in the State tab and in the event log.

[0.8.2]#

Security#

• The exported graph is built from an allowlist of SVG elements and attributes, and the exported diagram escapes every value it writes, instead of cleaning the result with regular expressions afterwards.

[0.8.1]#

Security#

• Downloads always use a non-renderable content type, so an exported image cannot be rendered by the page if its link is opened instead of downloaded.
• Exported SVG images are sanitized before leaving the page, and the graph export skips scriptable elements and attributes.

[0.8.0]#

Added#

• Global properties in Upon: property <name> always|eventually <expression> end, checked after every step over the state of every process, with the built-ins crashed, up, correct, t and the function defined.
• The FloodSet example declares agreement, validity and termination.
• Properties are reported in the event log (new Properties filter), among the counters, in the batch runner and by the command line tool, which exits with 1 when one breaks.

Changed#

• The FloodSet example stores its decision in a state variable, so that a property can observe it.

[0.7.0]#

Added#

• A batch runner (src/runner.js) that runs a scenario over many seeds without touching the page, with compact summaries and outcome grouping.
• A command line tool (bin/dsp.mjs) to run and check scenarios outside the browser, with exit codes for continuous integration.
• Documentation page: running scenarios outside the browser.

[0.6.1]#

Security#

• The CI workflow runs with read-only repository permissions.
• Downloaded scenario files are built from the application state instead of the text shown in the export dialog, and every download uses a generic content type.
• JSON from imported files, shared links and local storage is parsed without __proto__, constructor and prototype keys; stored settings are checked against their allowed values.
• Property paths used by form fields follow only own properties and refuse keys that could reach a prototype.
• The editor's syntax highlighting and line numbers are built as DOM nodes, so code is never interpreted as HTML.
• Translated blocks are restored from cloned nodes instead of re-parsed markup.

[0.6.0]#

Added#

• Logo, banner and social preview image.
• Settings menu: theme (system, light, dark), a palette for color vision deficiencies, interface language (English, Italian), presentation mode, keyboard shortcuts, welcome tour.
• Presentation mode for lectures: larger text, side panel hidden, remote clickers step through events.
• Welcome tour on the first visit.
• Export of the space-time diagram as SVG or PNG, and of the graph as SVG.
• Example gallery with thumbnails, topics and models.
• A browsable documentation site generated from docs/ with no extra dependencies.
• Changelog, citation file, code of conduct, security policy, issue and pull request templates.

Changed#

• Packets slow down as they approach their destination.

[0.5.1]#

Added#

• Full user documentation in docs/: getting started, concepts, assumptions and simplifications, engine, timing model, faults, language, library, examples, interface, teaching, troubleshooting.
• CONTRIBUTING.md with writing guidelines.
• A test that compiles every Upon program in the documentation and checks every link and anchor.

Fixed#

• A fault injected at the cursor could change earlier history when duplication was enabled.
• Messages dropped in transit did not update the FIFO state of their channel.
• Duplicates of a message dropped in transit were not recorded.
• Inputs sent to a crashed process changed the random values received by the others.

Changed#

• The FloodSet example uses four processes and seed 5.

[0.5.0]#

Added#

• Upon: functions with return and call, explicit binding with via, twenty new built-in functions.
• Module library: stubborn, perfect and FIFO links; best-effort, reliable, uniform reliable, FIFO, causal and probabilistic broadcast.
• Add module menu.
• Stack tab showing requests and indications between modules.
• Layers: messages colored by the module that originated them.
• Causality mode with causal past and future of an event.
• Examples: reliable broadcast with a sender crash, causal broadcast, gossip.

[0.4.0]#

Added#

• Layouts for phones, tablets, laptops and large monitors; touch support.

Changed#

• Faster rendering of large runs.

Fixed#

• Malformed stored scenarios no longer break the application.
• Keyboard shortcuts work after clicking a checkbox.

[0.3.0]#

Added#

• Crash-recovery with stable variables, link failures and partitions over time.
• Fault injection at the cursor.
• Example: failure detector across a partition and a recovery.

[0.2.0]#

Added#

• Animated execution on the topology, event-by-event playback, event injection at the cursor.

Changed#

• The whole interface and documentation are in English.

[0.1.0]#

Added#

• First version: Upon language, discrete-event engine, parametric timing model, topology editor, space-time diagram, examples.