Design

How Wyrd behaves

The rules behind the API: what a message is, what a process promises, and what happens when something goes wrong.

Five principles

1. Decisions are pure; effects belong to Wyrd. Business code decides. Wyrd delivers, stores, retries, compensates and times out.
2. Explicit over implicit. No hidden defaults that change behaviour. When something must be decided, the compiler (analyzers) asks for the decision instead of assuming one.
3. Guarantees are not options. What keeps the system consistent cannot be turned off.
4. Nothing fails silently. What Wyrd cannot resolve becomes visible and recoverable, never lost or stuck in silence.
5. Time limits are business decisions; slowness is not failure. A deadline is something the business chooses on purpose. A slow answer only makes a process wait.

Messages

Three kinds of message exist because they make different promises. Mixing them is the most common source of coupling in event-driven systems.

// An intention sent to exactly one owner
public sealed record ChargePayment(string OrderId, decimal Amount) : ICommand;

// An internal fact inside one bounded context
public sealed record PaymentCharged(string OrderId, decimal Amount) : IDomainEvent;

// A versioned public contract across boundaries
[IntegrationEvent("payments.payment-charged", Version = 1)]
public sealed record PaymentChargedV1(string OrderId, decimal Amount, string Currency)
    : IIntegrationEvent;

Slices

A slice owns one command: it decides from the current state and says how the state changes. Nothing else touches that state.

Processes

A process is linear: a trigger, steps and waits in order, and an optional outcome when it is compensated. There is no branching; an alternative path is another process. That is a Conscious limit: linear processes stay easy to read, simulate and version.

trigger event (correlated by key)
        │
        ▼
 step 1: send a command ──► Accepted ──► next step
        │                └─► Rejected ──► compensate (never retried)
        │                └─► Failed   ──► the step's retry policy decides
        │                                (exhausted: suspend, or .OrCompensate())
        ▼
 wait:  Await<Event>(key) ──► fact arrives ──► next step
        │                 └─► .Within(...) expires ──► compensate on purpose
        ▼
 step 2 ...
        ▼
 last step ──► Completed

Instances and the structure fingerprint

Steps

Retries: one layer

Compensation is a guarantee

Rejected at step 3
  undo step 2  (insists until it works, or suspends)
  undo step 1
  run the outcome command  (.OnCompensated(...))
  instance: Compensated

Fencing exists because a process that gives up on a step cannot know whether the step ran: a delayed copy may still execute later. The undo carries the id of the original command, and the owner decides atomically with its inbox.

gave up on ChargePayment (m1), outcome unknown
  send Undo(original = m1) to the same owner
  owner, in one transaction with its inbox:
     m1 ran?       yes ──► undo it
                   no  ──► fence m1: a late copy never executes
  a domain rejection of the undo is NOT proof that nothing ran

Waits and time

When Wyrd cannot resolve something: suspend

An instance is suspended, needing attention when:

• a step's retries are exhausted (a failure Wyrd cannot classify: an outage or a bug; suspending never cancels an order because of a bug, and a process may opt into compensating automatically instead with .Retry(3.Times).OrCompensate()),
• an undo's retries are exhausted,
• the outcome command fails after its retries,
• its definition's structure changed.

Suspending does not make the world consistent: the instance stays half-way. It makes the situation visible (status, reason, alert) and recoverable: an operator resumes it after a fix, or compensates it. Nothing is lost and nothing stays stuck in silence. ResumeAsync re-sends what the instance was doing with the same message id, so a command that did run is not run twice. CompensateAsync undoes a forward-suspended instance and fences the step it gave up on. A late success of the pending command resumes the instance on its own. Implemented A changed process structure suspends an instance the same way. Every host, in memory and on EF Core, offers these operators.

Statuses

Suspended carries its reason (ReasonOf) and replaced the earlier Failed status.

┌───────────── fact arrives ─────────────┐
            ▼                                        │
 trigger ──► Running ──► Awaiting ───────────────────┘
               │            │
               │            └── .Within expires ──┐
               ▼                                   ▼
          Completed                      compensating (Running)
                                                   │
                                                   ▼
                                             Compensated

 retries exhausted, undo exhausted,
 outcome failed, definition changed ──► Suspended
 (a late success also resumes it)         │ ResumeAsync or CompensateAsync

Delivery

Read models

Conscious limits

Each of these is a choice with a stated reason and a way out, not an oversight.