@causal-order/testing

Qualify the causal-order package stack under transport faults, downstream outages, dedupe bypass, buffered recovery, and replay. @causal-order/testing drives installed packages, records operational evidence, and produces scenario-aware verdicts.

Published package version: v0.3.3

Stack Position

@causal-order/transport -> [@causal-order/monitor] -> @causal-order/dedupe -> causal-order

The normal delivery path is transport to dedupe to causal ordering. When enabled, monitor sits between transport and dedupe to provide health-aware routing, bounded buffering, degraded operation, and controlled recovery. Buffered events replay through restored dedupe before returning to causal ordering.

@causal-order/testing sits outside that delivery path:

@causal-order/testing = workload + faults + orchestration + artifacts + verdicts

The harness does not replace or reimplement transport, monitoring, deduplication, or causal ordering. Those behaviors remain owned by the installed packages.

Install and Requirements

Full monitor-aware stack:

npm install @causal-order/testing @causal-order/transport @causal-order/monitor @causal-order/dedupe causal-order

Stack without monitor:

npm install @causal-order/testing @causal-order/transport @causal-order/dedupe causal-order

• Node.js >=22.13.0
• ESM-only output

| Package | Qualified line | Role | | --- | --- | --- | | causal-order | 1.0.x | causal ordering runtime | | @causal-order/dedupe | 1.2.x | structured duplicate filtering | | @causal-order/monitor | 0.6.x | optional buffering, routing, and replay | | @causal-order/transport | >=0.2.0 <0.3.0 | acknowledged transport runtime and bounded-stop testing adapter |

When to Use It

Use this package to:

• validate the installed stack rather than isolated substitutes
• inject transport, dedupe, and causal-order outages
• verify monitor routing, buffering, replay, and retry behavior
• distinguish expected degraded operation from contract failure
• retain artifacts for operational inspection and contract verification

When Not to Use It

This package is not:

• an application runtime or production delivery stage
• a replacement for package-owned unit and integration tests
• a durable queue, monitoring service, or dedupe implementation
• a benchmark result that applies independently of the selected profile, adapter, and environment

Runtime Validation

Use the transport package's published testing adapter to exercise the real transport path:

causal-order-testing-adapter-runtime \
  --adapter @causal-order/transport/testing \
  --duration 20m \
  --time-scale 60 \
  --profile expected-production-3way-mesh

Run the built-in deployment simulation without a transport adapter:

causal-order-testing-runtime \
  --duration 20m \
  --time-scale 60 \
  --profile expected-production-3way-mesh

Run a rejoin-aware profile:

causal-order-testing-runtime-rejoin \
  --duration 20m \
  --time-scale 60 \
  --profile expected-production-mesh-dark-jitter \
  --dark-nodes edge-b \
  --jitter-nodes edge-c

Artifacts are written under artifacts/runs/ in the caller's working directory unless --output-dir is supplied.

v0.3.1 shutdown contract

Adapter runs stop in a defined order. The harness stops workload ingress, waits for HarnessAdapter.stop() to complete its transport callback barrier, reconciles monitor recovery to terminal state, drains lifecycle observation, closes and drains causal ordering, and only then derives the final verdict.

Callbacks accepted while HarnessAdapter.stop() is pending remain valid and are processed. After that promise resolves, the adapter must not issue another event, peer-state, or error callback. A callback after the barrier is a contract failure rather than silently changing final evidence.

Successful monitor-aware completion requires no pending monitor rows or tracked monitor operations, a drained lifecycle queue, settled ordering, and final evidence captured after those barriers.

summary.json records structured shutdown evidence, including phase and milestone history, callback-boundary and terminal counters, interruption state, and retained primary or cleanup failures. The complete contract and field interpretation are documented in the integration reference.

Monitor contracts

Healthy monitor flow:

causal-order-testing-adapter-runtime \
  --adapter @causal-order/transport/testing \
  --monitor \
  --duration 20m \
  --time-scale 60 \
  --profile monitor-healthy-rolling-4h \
  --monitor-scenario monitor-healthy-rolling-4h \
  --run-name monitor-healthy

Order outage with buffered recovery through dedupe:

causal-order-testing-adapter-runtime \
  --adapter @causal-order/transport/testing \
  --monitor \
  --duration 20m \
  --time-scale 60 \
  --profile monitor-order-outage \
  --monitor-scenario monitor-order-outage \
  --run-name monitor-order-outage

Dedupe outage with explicit throttled bypass:

causal-order-testing-adapter-runtime \
  --adapter @causal-order/transport/testing \
  --monitor \
  --duration 20m \
  --time-scale 60 \
  --profile monitor-dedupe-bypass \
  --monitor-scenario monitor-dedupe-bypass \
  --run-name monitor-dedupe-bypass

Replay failure and retry backoff:

causal-order-testing-adapter-runtime \
  --adapter @causal-order/transport/testing \
  --monitor \
  --duration 20m \
  --time-scale 60 \
  --profile monitor-replay-retry-backoff \
  --monitor-scenario monitor-replay-retry-backoff \
  --run-name monitor-replay-retry

The core distinction is contractual:

• monitor-order-outage buffers work and must replay through restored dedupe.
• monitor-dedupe-outage permits monitor's throttled direct-to-order bypass; duplicates can reach causal ordering because dedupe is not on that degraded route.

Order-outage scenarios also enforce replay retention before ingress starts. The runtime derives the bounded outage duration, adds a three-minute replay/drain margin, asks the dedupe adapter to activate that window, and verifies the reported active window. A configured maximum below the required horizon fails preflight. Deployments with an unbounded outage horizon require a durable processed-event identity ledger; a finite in-memory sliding window cannot make that guarantee.

Compatibility aliases remain accepted:

| Accepted alias | Canonical scenario | | --- | --- | | monitor-recovery-through-dedupe | monitor-order-outage | | monitor-dedupe-bypass | monitor-dedupe-outage |

Artifacts record canonical identifiers so equivalent runs remain comparable.

Verdicts

Adapter runs write a scenario-aware verdict to summary.json:

| Verdict | Meaning | | --- | --- | | pass | execution and the expected stack contract succeeded | | pass_with_expected_degradation | the configured bypass contract succeeded with explicitly permitted degradation | | fail_contract | execution completed but required routing, replay, drain, dedupe, or ordering evidence was missing or violated | | invalid_run | execution failed or was interrupted before contract validation completed |

fail_contract and invalid_run produce a non-zero process exit while preserving run artifacts and shutdown evidence.

Structured dedupe evidence records decision reasons and identity sources from @causal-order/[email protected]. Monitor summaries can also include versioned operator, capacity, and lifecycle snapshots, lifecycle-flush status, replay evidence, and bounded monitor-operation metrics.

Inspect runs

causal-order-testing-latest
causal-order-testing-summary artifacts/runs/<run-folder>
causal-order-testing-compare artifacts/runs/<older-run> artifacts/runs/<newer-run>
causal-order-testing-duplicates artifacts/runs/<run-folder>

The summary and comparison commands also read compatible wall-clock transport runs under artifacts/transport-runs/.

Read adapter results in pipeline order:

transport delivered
  -> dedupe accepted/dropped
  -> causal-order ordered/anomalies

Monitor-enabled runs add routing, buffering, replay, retry, capacity, lifecycle, and final-drain evidence.

Command surface

| Command | Purpose | | --- | --- | | causal-order-testing-runtime | built-in deployment simulation | | causal-order-testing-runtime-rejoin | rejoin-aware deployment simulation | | causal-order-testing-adapter-runtime | adapter-driven installed-stack validation | | causal-order-testing-latest | locate and summarize the latest run | | causal-order-testing-summary | render one run report | | causal-order-testing-compare | compare two runs | | causal-order-testing-duplicates | inspect duplicate leakage evidence |

Use --help on any command for the complete option surface.

Library surface

The root export provides configuration, simulation, scenario, and adapter contracts:

import {
  buildConfig,
  buildRejoinHarnessConfig,
  createSimulationClock,
  formatDuration,
  parseDurationToMs,
  resolveMonitorScenario,
  resolveMonitorScenarioId,
  type HarnessAdapter,
  type HarnessAdapterFactory,
  type HarnessPipelineProvider,
} from "@causal-order/testing";

Focused exports:

• @causal-order/testing/transport
• @causal-order/testing/dedupe
• @causal-order/testing/order
• @causal-order/testing/providers/default

The CLI runtime modules are package executables, not import-first public modules.

Integration and release history

• Integration reference
• Changelog

The integration reference retains the detailed adapter contract, runtime ownership, artifact interpretation, transport workflow, monitor scenario catalog, and operational notes that previously lived in this README.

License

MIT