add scheduler as functional requirement

docs/proposals/2023-10-05-proposal-v0.2.md

@@ -1,4 +1,4 @@
-# Proposal v0.2 - 2023-10-05
+# DRAFT: Proposal v0.2 - 2023-10-05
 
 ## Objective
 Currently, in v0.1 of the MFM, we have built a lot of components as a PoC and learning process to build a finance machine that can query and execute operations on-chain and, on top of that, manage portfolios of crypto assets.
@@ -9,17 +9,24 @@ This Proposal for v0.2 is focused on a full redesign and refactor that should ad
 - Operation: a task available to be performed (usually on-chain); it's described by a set of states that needs to be processed to achieve the final task objective
 - Machine: a fun name matching the project name, which is a set of operations to be performed (usually on-chain); it's composed of a group of Operations, which in turn is composed of a collection of the states filtered by tags 
 - State: a minimal unit of pointer to the previous state, state data (input) and handler; those handlers perform minimal tasks (usually deterministically) that will be composed to make an Operation
+- Scheduler: is the responsible for execute and make the control flow for states, and for push and pull states input/output (it should be multitask in the future allowing concurrency and parallelism based on state tags)
 
-## Goals
-- Build a state machine library with state-local storage that enables us to compound states and use it as input for a new state
-- The state-local storage needs to be an implementation of the state storage traits
-- The state storage traits need to be based on a commit message process that should enable a non-local storage implementation in the future
+## Functional requirements
+- A state machine with handlers and state storage (context) that enables us to compound states and use it as input for a new state
+- A state storage should be a trait (based on a commit message process?) that should enable a non-local storage implementation in the future
+- The state-local storage as the first implementation of the state storage traits
 - Each state needs to have handlers to read the input data of the state and output a compounded state for the next state
 - Each state handler needs to operate in an isolated form and behave as determined as possible
 - Each state must have tags indicating its kind of state (e.g., config, fetch_data, compute, execute, report, report_operator, report_operation, etc.)
 - States that apply side-effects need to be tagged as is (e.g. apply_side_effect)
+- Non-deterministic states needs to be tagged as is (e.g. impure)
+- A scheduler will run the state handlers and control flow
+- A scheduler will control flow with error handlers based on common error types
+- A scheduler error handler should be replaceable
 - Describe any operation that should be a sequence of states with a start input
-- Operation can be composed by composing the states of each operation 
+- Operation can be composed as a Machine by composing the states of each operation 
+- An Operation should be able to create their own error handler and replace the default scheduler error handler
+- Machine should be a set of operations that will be composed by a series of sub states of all those operations filtered by tags (e.g. excluding user interaction inside an Machine with five Operations)
 - The state-local storage needs to carry historically all states data until the operation finish
 - Design and implement a report that can read states and report to the user (or to the program like a JSON)
 - Any UI can invoke an operation; the first one should be CLI
@@ -106,3 +113,15 @@ It's a Machine which is composed of a subset of the states of three Operations:
 - generate_report;
 - report_to_operator; (should be always on by defined in a "always list of tags" with a report_operation tag, which will make all states of a report operation always execute)
 
+## Future possible extension of this functional requirements
+- Scheduler can be multitasking using concurrency and parallelism of state handlers bases on tags
+- Scheduler can instrument all state executions with input and output data by tracing the executions and the state storage (e.g. implementing opentelemetry tracing)
+- State storage can have multiple implementation like databases or caches
+- We can "replay" or "continue" any operation or machine interruptions just re-executing the next state of the last confirmed state with the correct input
+
+## References
+- https://en.wikipedia.org/wiki/Finite-state_machine
+- https://en.wikipedia.org/wiki/Event-driven_finite-state_machine
+- https://en.wikipedia.org/wiki/State_pattern
+- https://en.wikipedia.org/wiki/Scheduling_(computing)
+