causal-order Wiki

This wiki is the conceptual layer of the project. It explains the mental model behind the library, why the problem is harder than ordinary timestamp sorting, and how causal-order tries to stay honest without becoming unusable.

If you want the quickest path into the package, start with the README. Use this wiki when you want the deeper explanation behind what the guides and API reference are doing. For package-facing usage, examples, and operational walkthroughs, use the guides, the API reference, and the examples folder.

How To Use These Docs

Use each doc surface for a different job:

• README for the shortest path to understanding the library
• guides for practical usage, workflows, and package-facing documentation
• this wiki for concepts, terminology, and deeper explanation

Start Here

If you are new to the project, read these pages first:

1. What This Library Is
2. The Problem With Distributed Timelines
3. Confidence Levels
4. Concurrent vs Unknown
5. Streaming Finality
6. Streaming Recovery and Resync

Practical Next Steps

If you already understand the concepts and want to use the package:

• start with Quick Start Scenarios
• see Policy Guidance for operational strictness and late-arrival choices
• see Replay Inspection Workflow for bounded replay inspection
• see Streaming Reconciliation Workflow for stream correction and reconciliation
• see Operator Metrics Guide for operator-facing metrics and summaries

Concept Pages

• What This Library Is
• The Problem With Distributed Timelines
• Why Timestamp Sorting Fails
• Confidence Levels
• Concurrent vs Unknown
• Streaming Finality
• Streaming Recovery and Resync
• Realistic Workloads
• Stress Hardening
• Design Philosophy
• When to Use causal-order

The Core Idea

The library does not try to make distributed event order magically certain. It tries to answer a more honest question:

What can be ordered safely, what is only inferred, what can be justified as concurrent, and what should remain unknown?

That means the value of the library is not just:

• sorting events

It is also:

• showing when order is justified
• showing when order is only derived
• refusing to flatten concurrency into fake sequence
• making suspicious or weak metadata visible

So the project is not only about explaining distributed timelines after the fact. It is about giving real systems a deployable ordering runtime, with event integrity as the outcome, without treating global clock sync as the source of truth.

Project Standard

causal-order should feel easy to use at the surface, but difficult to misuse into false certainty.