scala-amoris

"Beholding the unchanging, divine Form of Beauty itself."

— LoveStage.AbsoluteBeauty.description in modules/core/src/main/scala/amoris/LoveStage.scala

scala-amoris is a small Scala 3 demo about how to model a distributed system that eventually agrees, even when a host is temporarily down.

The domain model is intentionally small: a Soul carries name, wisdom, and currentStage, while LoveStage defines the six stages of ascent.

• data stays on a host (SiloRef[T] points to where it lives)
• functions travel as messages (map / flatMap add steps)
• work is lazy until you ask for a result (send)
• if a host is down, delivery is queued and retried after recovery

In short: this is a lineage-based, message-passing system that prefers eventual consistency over fail-fast behavior.

From a distributed-systems perspective, this mirrors a literature-backed idea: stationary data, mobile functions, lazy lineage construction, and explicit forcing operations (send) to drive convergence after interruptions.

Think of each host as a warehouse.

• A SiloRef[T] is a typed shipping label for a value of type T in one warehouse.
• map and flatMap do not run work immediately; they build a lineage (an execution history).
• send starts delivery of that lineage through the cluster's message queue.
• If a warehouse is down, messages wait in its queue and run when it comes back.

Because of this model, the system can converge after interruptions. That is the eventual-consistency behavior this demo focuses on.

The local ascent logic is written once in LadderOpsK[F[_]]. F[_] means "some effect type" (for example Option, Future, or your own type).

• LadderOpsK defines the rules.
• LadderEffect[F] provides how effects happen (logging, delay, composition).
• LadderOps and ScalaAmoris keep a simple default API for normal use.

• expose delivery lifecycle metrics (counts by Pending, Processing, Delivered, Failed) for dashboards
• add per-host inFlightDeliveryIdsFor(host) to complement queue snapshots
• add deliveryHistory(deliveryId) with attempt timestamps for retry tracing
• add lastFailureFor(deliveryId) and host-level failure summaries for diagnostics
• add drainUntilIdle(host, maxSteps) / drainAllHostsUntilIdle(maxSteps) safety bounds for deterministic tests
• add queue age and retry-depth snapshots for "is this host catching up?" checks
• document intended ordering guarantees (FIFO per host queue vs eventual-only completion)

# Run the simulation
sbt "app/run"

# Run all tests
sbt "tests/test"

CC0 1.0 Universal — public domain. See also THIRD_PARTY_NOTICES.md.