Chapter 1 — DSM Responsibilities and Applicability

Chapter objective: After completing this chapter, a developer can decide whether a state belongs in DSM by examining data responsibility and recovery behavior.

Learning objectives

1. Describe the coordination problem that DSM solves.
2. Distinguish business facts, coordination state, event history, and analytical data.
3. Explain why peer repair does not make DSM a database replacement.
4. Make an initial storage decision for the four data categories in the fulfillment case.

Prerequisites

• Ability to read basic Java interfaces.
• Familiarity with database transactions and multi-instance services.
• This chapter does not require a running DSM instance or knowledge of replication protocols.

Case progress

The fulfillment system runs several API and worker instances. They share service routes, order-shard ownership, and request counts. Orders, inventory, and payments already have authoritative systems.

This chapter defines the responsibility boundary. Chapter 2 creates the first Runtime.

The coordination problem DSM solves

Consider a dangerous proposal: a team sees that DSM replicates data and plans to move order state into DSM and remove the database.

The decisive question is not whether DSM can serialize an Order. Order state is a business fact that needs transactional constraints, audit history, and a determinate write result. Replica convergence after network recovery cannot reconstruct a lost payment or revoke a success response already returned to a customer.

DSM fits a different category: relatively small coordination state needed while services run, recoverable from peers or rebuildable from an authoritative source.

Divide storage by data responsibility

The architecture assigns three responsibilities:

• Transactional databases retain orders, inventory, payments, and other business facts.
• DSM Runtime retains route hints, leases, mergeable counters, and other coordination state.
• Messaging or event systems retain events that require reliable delivery and historical replay.

One application may use all three. Choosing DSM does not exclude a database or event system.

DSM through its public contract

DsmRuntime is the public facade for several typed collections:

<E extends DsmEntity<E>> DsmRegister<E> register(CollectionSpec<E> spec);

<E extends LeaseEntity<E>> DsmLeaseRegister<E> leaseRegister(
        LeaseCollectionSpec<E> spec);

<E extends DsmEntity<E>, S extends MergeableState<S>>
DsmCrdtCollection<E, S> crdt(
        CrdtCollectionSpec<E, S> spec,
        StateMerger<E, S> merger);

The entry points answer different coordination questions:

Chapters 5–9 develop these semantics. At this stage, identify the business invariant before choosing a collection.

First verifiable increment: classify state

Open classification-cases.json and classify all eight candidates before reading the reference answer:

• transactional-fact: a business fact that needs transactions and audit.
• coordination-state: runtime state that can be repaired or rebuilt.
• event-history: events that need reliable delivery or replay.
• analytical-data: data intended for large-scale query and analysis.

Run the asset check:

npm test -- --test-name-pattern="chapter 01 classification"

The command validates the chapter asset and reference answer. It does not run DSM.

Responsibility details

Business facts depend on commit history

An order transition from PENDING to PAID usually accompanies a payment record, inventory change, and audit entry. The system identifies the successful transaction, the actor, and the compensation path through its transactional contract. DSM's collection API is not a cross-resource transaction protocol.

Orders, inventory deductions, and payment ledgers therefore stay in transactional systems.

Coordination state supports runtime decisions

A route hint tells a gateway which fulfillment instance to call. It may be temporarily stale and can be republished by a health source. If a node misses an online delta, repair can bring its current state forward.

That state can fit DSM, provided the stale window and failure behavior are explicit.

Event history needs delivery guarantees

ChangeStream observes collection changes. It is not a durable event log. A system that requires replay of every OrderPaid event uses a message platform, outbox, or event store.

Large-scale analysis needs a different data model

DSM collections center on keys and coordination semantics. They do not provide joins, secondary indexes, or analytical queries over large datasets. High-volume logs and metrics belong in corresponding data pipelines.

Counterexample and fault injection

Suppose inventory balance is stored in a Register:

1. Node A reads a balance of 1 and returns a successful deduction.
2. During a partition, node B also reads 1 and returns success.
3. After recovery, the Register deterministically retains one visible value.

The replicas converge, but two customers received success. Convergence did not revoke the second sale or create an auditable inventory transaction. DSM applicability therefore depends on whether business responses are reversible and whether transactional history is required—not only on whether an object is serializable.

Why this happens

A Register selects a deterministic visible result from candidate state. It does not coordinate several business resources or withdraw external effects.

Keep one boundary in view:

Repair restores replica state; it does not repair business commitments already made outside DSM.

Revised state model

Replace “inventory balance” with “the preferred route to the inventory service” and ask:

1. Can a health source regenerate it after loss?
2. Can a caller retry or switch routes after reading a stale value?
3. Is complete modification history unnecessary?
4. Is a deterministic winner acceptable when publishers race?

Four positive answers make the route hint a better Register candidate than inventory balance.

Common misconceptions

Treating “memory” as a local cache

DSM state is managed by a Runtime and can propagate through sync and repair. It is neither a Map exposed to every JVM nor a simple local-cache wrapper.

Treating replicas as proof that data cannot be lost

Durability still depends on persistence configuration, topology, correlated failures, backup, and recovery. Several in-memory replicas do not replace database backups.

Selecting a collection before finding the business reason

“CRDT is the most advanced option” is not a selection criterion. Without concurrent local updates and a valid merge model, a CRDT only adds modeling and verification cost.

Understanding check

1. What makes a service-discovery address a possible Register candidate?
2. Why can an eventually convergent inventory value still oversell?
3. Should data requiring customer, time, and status queries use DSM as its primary store?
4. Why can a worker heartbeat fit DSM while the complete history of finished tasks does not?

Experiment

Classify these states as business facts, coordination state, event history, or analytical data:

• Current order status.
• Fulfillment-service route hint.
• Shard owner and lease expiry.
• Per-node request count.
• OrderPaid event history.
• Payment ledger entry.
• Request-latency histogram.
• Temporary feature flag.

Compare the result with the reference answer. A feature flag is not classified mechanically: its authoritative source, stale window, rollback needs, and business effect still matter.

Experiment acceptance card

Review

• DSM stores distributed coordination state; it is not a universal shared-data system.
• Business facts, coordination state, event history, and analytical data need different guarantees.
• Register, Lease, and CRDT address current value, ownership, and mergeable updates.
• Repair restores replica state; it does not revoke business responses.

Next

Chapter 2 starts a minimal DsmRuntime, creates the route-hints Register, and performs the first write and read.

Evidence links

• DsmRuntime
• DsmRegister
• DsmCrdtCollection
• DSM project constraints
• Phase 0 baseline validation