update repository

Author: leiding01

examples/ra_conflict.json …e/examples_experimental/ra_conflict.jsonexamples/ra_conflict.json renamed to archive/examples_experimental/ra_conflict.json examples/ra_conflict.json renamed to archive/examples_experimental/ra_conflict.json

@@ -0,0 +1,39 @@
+\chapter{User Manual}
+\label{app:user-manual}
+
+\section{Running the Tool Locally}
+From the repository root, start a local server:
+\begin{verbatim}
+python -m http.server 5500
+\end{verbatim}
+Open:
+\begin{verbatim}
+http://localhost:5500/
+\end{verbatim}
+
+\section{Basic Usage}
+\begin{itemize}
+  \item Select an algorithm (Token Ring or RA) and choose the number of processes.
+  \item Use \textbf{Request CS} to issue a request.
+  \item Use \textbf{Step} to progress deterministically.
+  \item Use \textbf{Run/Pause} for automated playback.
+  \item Observe the process table, message queue table, trace, safety label, and preview canvas.
+\end{itemize}
+
+\section{Fault Injection}
+\begin{itemize}
+  \item Token Ring: use \textbf{Drop token}, \textbf{Regenerate token}, \textbf{Crash}, and \textbf{Recover}.
+  \item RA: use \textbf{Drop next in-flight msg} and \textbf{Arm drop-next-send}.
+\end{itemize}
+
+\section{Scripted Demos}
+Use the scripted demo controls to load deterministic scenarios such as crash/recover and RA tie-break demonstrations.
+
+\section{Evidence Export}
+Use the export controls to generate:
+\begin{itemize}
+  \item state JSON,
+  \item trace TXT,
+  \item preview PNG.
+\end{itemize}
+These artefacts support reproducible evidence collection.

examples/ra_delayed_link.json …amples_experimental/ra_delayed_link.jsonexamples/ra_delayed_link.json renamed to archive/examples_experimental/ra_delayed_link.json examples/ra_delayed_link.json renamed to archive/examples_experimental/ra_delayed_link.json

@@ -0,0 +1,21 @@
+\chapter{Test Cases Summary}
+\label{app:test-cases}
+
+This appendix summarises the minimum manual test set executed for the freeze baseline.
+
+\section{Token Ring}
+\begin{itemize}
+  \item \textbf{TR-01 Basic mutual exclusion:} issue requests from multiple processes and verify that only one process enters the critical section at a time.
+  \item \textbf{TR-02 Token loss and regeneration:} drop the token, observe loss of progress, regenerate the token, and verify recovery.
+  \item \textbf{TR-03 Crash and recover:} crash a process, observe state and trace changes, then recover the process.
+\end{itemize}
+
+\section{Ricart--Agrawala}
+\begin{itemize}
+  \item \textbf{RA-01 Basic request/entry/release:} request the critical section and step through REQUEST/REPLY delivery until entry.
+  \item \textbf{RA-02 Tie-break:} load the scripted tie-break scenario and verify deterministic ordering under equal timestamps.
+  \item \textbf{RA-03 Drop next in-flight message:} drop a queued message and observe the stalled state with explicit missing-REPLY explanation.
+  \item \textbf{RA-04 Drop-next-send:} arm the send-side drop and observe the resulting stalled state.
+\end{itemize}
+
+For each case, an evidence triplet (state JSON, trace TXT, preview PNG) is exported and indexed separately.

examples/ra_sequential.json …examples_experimental/ra_sequential.jsonexamples/ra_sequential.json renamed to archive/examples_experimental/ra_sequential.json examples/ra_sequential.json renamed to archive/examples_experimental/ra_sequential.json

@@ -0,0 +1,49 @@
+\chapter{Introduction}
+\label{ch:introduction}
+
+\section{Motivation}
+Distributed systems underpin modern computing, but their behaviour is often difficult to understand from static material because correctness depends on concurrency, message ordering, and assumptions about failures \cite{tanenbaum2017distributed,coulouris2011distributed,lynch1996distributed}. Mutual exclusion is a classic example: a set of distributed processes must coordinate access to a shared critical section without relying on shared memory or a global clock.
+
+Learners commonly struggle to connect algorithm descriptions to concrete executions. This challenge becomes more severe when faults are introduced, since safety properties may remain intact even when progress is lost. Such distinctions are difficult to communicate through static diagrams alone. This motivates the development of an interactive teaching tool that makes state, causality, and fault consequences directly observable.
+
+\section{Project Aim and Objectives}
+The aim of this project is to develop an interactive educational artefact for visualising distributed mutual exclusion and its behaviour under faults and recovery conditions.
+
+The specific objectives are:
+\begin{itemize}
+  \item implement a technically correct simulation that preserves the safety invariant of mutual exclusion,
+  \item provide step-by-step execution with an explanatory trace,
+  \item support representative token-based and message-based algorithms,
+  \item support fault injection and recovery to illustrate safety vs liveness trade-offs,
+  \item provide reproducible evidence export,
+  \item and evaluate the artefact in terms of correctness, usability, and reproducibility.
+\end{itemize}
+
+\section{Scope}
+The delivered system focuses on two representative approaches:
+\begin{itemize}
+  \item \textbf{Token Ring}, a token-based mechanism that provides an intuitive model of exclusivity.
+  \item \textbf{Ricart--Agrawala (RA)}, a message-based algorithm using Lamport-style timestamps \cite{ricart1981optimal,lamport1978time}.
+\end{itemize}
+
+The system is teaching-oriented rather than production-oriented. The network model is intentionally simplified to support controlled observation and reproducibility. Message loss in RA is used to demonstrate that liveness can fail while safety is preserved; retransmission and failure detectors are not implemented.
+
+\section{Contributions}
+The main contributions of the project are:
+\begin{itemize}
+  \item a browser-based, dependency-free Distributed Mutual Exclusion Explorer,
+  \item support for both Token Ring and an RA teaching-oriented prototype,
+  \item explicit fault injection and recovery mechanisms,
+  \item scripted demos for deterministic replay,
+  \item an evidence export pipeline (state JSON, trace TXT, preview PNG),
+  \item and a reproducible testing and evidence framework built around a freeze baseline.
+\end{itemize}
+
+\section{Report Structure}
+Chapter~\ref{ch:background} reviews distributed mutual exclusion, logical time, fault assumptions, and educational visualisation literature.
+Chapter~\ref{ch:design} presents the specification and design of the artefact.
+Chapter~\ref{ch:implementation} describes implementation details.
+Chapter~\ref{ch:testing} covers testing strategy and execution.
+Chapter~\ref{ch:evaluation} evaluates correctness, usability, and reproducibility.
+Chapter~\ref{ch:professional} discusses professional issues.
+Chapter~\ref{ch:conclusion} concludes the report and outlines future work.