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.

---

Modules

Module	Description
core	domain model, local ladder ops, and distributed primitives (SiloRef, map, flatMap, send, cache)
app	runnable local + distributed demo
tests	MUnit unit tests and ScalaCheck property suites

How it works

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.

Higher-kinded types

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.

Progressive delivery introspection

Delivery introspection is designed to make eventual completion observable rather than assumed. As work moves through retries, recovery, and final delivery, the system keeps a cumulative record of what happened so earlier states are not erased by newer ones. This gives operators and tests a clear narrative of convergence: not just that a message eventually arrived, but the path it took through delay, processing, and resolution.

The model emphasizes visible evidence at both current-time and historical levels. You can inspect what is pending now, what is actively being processed, and what has failed or completed, while also preserving enough history to understand whether a host is catching up or repeatedly struggling. Queue handling is FIFO within each host queue, but completion remains eventual across the system, so global finish order is intentionally treated as asynchronous and non-deterministic.

Quickstart

# Run the simulation
sbt "app/run"

# Run all tests
sbt "tests/test"

Compiler Optimizations

Technique	Where
-release:11 (Java 11 JIT target)	build.sbt
Scala 3 inline def — compile-time expansion	LoveStage.isApex, Soul.isEnlightened, LadderOps.nextStage
final val — constant folding	LadderOps.wisdomPerStage

License

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