v1 conformance tests guide (non-normative)

    This guide describes how to validate IndexBus v1 behavior using a conformance-style test suite.

    It is non-normative; the normative contract is the v1 spec.

    • Spec: ../spec/v1-semantics.md
    • Spec: ../spec/v1-failure-lifecycle.md

    Goal

    Provide a stable set of tests that:

    • enforce the v1 behavioral contract,
    • prevent accidental semantic drift,
    • help independent implementations validate correctness.

    Conformance style rules

    These are the default constraints for v1 conformance tests:

    • Prefer deterministic, in-process layouts and execution.
    • Use local/in-process harnesses where possible.
    • Avoid cross-process and network integration unless the spec item itself is explicitly about cross-process behavior.
    • Keep assertions topology-based.
    • Assert invariants that hold regardless of OS scheduling (ordering, boundedness, single-delivery, progress-after-consume).
    • Do not assert fairness, latency, or timing-sensitive behavior.

    What to test (mapping to spec)

    Start with the "Conformance checklist" in the semantics spec and ensure each item has a runnable test.

    Examples:

    • SPSC FIFO ordering and Full behavior.
    • MPSC per-producer ordering.
    • Fanout broadcast partial delivery is permitted (and never violates per-consumer queue invariants).
    • Fanout work-queue never delivers the same message to two consumers.
    • Credits: no-credit consumers are skipped; park policies avoid dequeuing.
    • State stream never returns a torn snapshot.

    Appendix C checklist → tests

    This table maps the semantics spec Appendix C items to concrete tests.

    Notes:

    • Some items are covered by unit tests in src/tests.rs; others are covered by integration tests in tests/.
    • Prefer adding new conformance coverage as integration tests to keep the mapping stable.
    Spec areaChecklist item (summary)Test(s)
    Events (SPSC)FIFO ordering preservedcrates/indexbus-core/tests/conformance_events.rs (v1_spsc_fifo_order_preserved)
    Events (SPSC)Bounded capacity; Full at saturation; progress after receivecrates/indexbus-core/tests/conformance_events.rs (v1_spsc_full_then_progress_after_recv)
    Events (SPSC/MPSC)Reject TooLarge publishcrates/indexbus-core/tests/conformance_events.rs (v1_publish_rejects_too_large); crates/indexbus-core/tests/production.rs
    Events (MPSC)Per-producer ordering preservedcrates/indexbus-core/tests/conformance_events.rs (v1_mpsc_per_producer_ordering_preserved_under_contention)
    Fanout (core primitive)Broadcast delivers to all consumerscrates/indexbus-core/src/fanout.rs unit tests
    Fanout (core primitive)Work-queue delivers to exactly one consumercrates/indexbus-core/src/fanout.rs unit tests
    Fanout (core primitive)Bounded capacity; Full at saturation; progress after all consumers receivecrates/indexbus-core/tests/conformance_fanout_queue_full.rs (v1_fanout_full_then_progress_after_all_consumers_drain)
    Fanout (router loop)Broadcast: routes via loop runner; per-source order preserved under batchingcrates/indexbus-route/src/tests.rs (broadcast_delivers_to_all_consumers, mpsc_source_broadcast_routes_messages, batching_preserves_per_source_order_broadcast)
    Fanout (router loop)Work-queue: delivers to exactly one consumercrates/indexbus-route/src/tests.rs (work_queue_delivers_to_one_consumer)
    CreditsNo-credit consumers are skipped (eligibility masks)crates/indexbus-route/src/tests.rs (credits_broadcast_drop_no_credit_when_consumer_depth_reaches_limit, credits_workqueue_only_selects_eligible_consumers)
    CreditsPark avoids dequeuing when none eligible; routes once eligiblecrates/indexbus-route/tests/conformance_credit_park.rs (v1_credit_park_avoids_dequeue_when_none_eligible)
    CreditsDrop: dequeues even when none eligible; counts as no-credit dropcrates/indexbus-route/tests/conformance_credit_drop_detach.rs (v1_credit_drop_dequeues_and_drops_when_none_eligible)
    CreditsDetach: detaches after threshold; reattaches once depth decreasescrates/indexbus-route/tests/conformance_credit_drop_detach.rs (v1_credit_detach_detaches_after_threshold_and_reattaches_with_hysteresis)
    Blocking wakeBackpressurePolicy::Block wakes on consumer progresscrates/indexbus-route/tests/conformance_backpressure_block.rs (v1_backpressure_block_wakes_on_consumer_progress_when_credit_parked)
    StateParity protocol: no torn snapshotscrates/indexbus-core/tests/state.rs (state_concurrent_publish_and_read_never_returns_torn_snapshot)
    • Router loop: explicit “consumer queue full → drop (broadcast) / all-full drop (work-queue)” attribution semantics at the integration-test level (avoid relying on unit tests only).

    Where to place tests

    Recommended structure:

    • Put core semantic tests near the implementation, e.g. crates/indexbus-core/tests/.
    • Add end-to-end router loop tests under crates/indexbus-route/tests/.
    • Prefer the local/in-process transport (indexbus-transport-local) for deterministic tests.

    Running tests

    • Workspace tests: cargo test
    • Per-crate: cargo test -p indexbus-core

    Performance safety

    Conformance tests should avoid asserting micro-timing and should not require high-resolution timers. Prefer:

    • deterministic topology,
    • bounded loops,
    • explicit yields/backoffs if needed.

    What conformance does not guarantee

    • It does not guarantee fairness.
    • It does not guarantee durability or replay.
    • It does not make best-effort observability counters exact.
    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index