Skip to main content

Module model

Module model 

Available on crate feature proptest only.
Expand description

The model-based half of the suite: a store driven through a generated sequence of operations, checked against a model of what the log should be.

§What this adds that the named rules cannot

Every rule in rules is a worked example: these events, this query, that result. Twenty-seven of them were measured letting four plausible wrong adapters through, and the reason is combinatorial rather than editorial — query × from × to × backwards × limit × condition × position policy is a space no hand-written example set covers, and the interactions are exactly where an adapter’s generated SQL goes wrong. This module generates that space instead of enumerating it.

It is additive, in the same sense the concurrency family is: it replaces no rule. A named rule says what is wrong when it fails; this one says which sequence made it wrong, minimised, and it is the only thing in the suite that ever runs read against a store whose contents it did not choose.

§Why the model is not agreeing with itself

The model is built on Query::matches and AppendCondition::is_violated_by, and that is not circular: each is pinned to an independently-written naive definition by a property test in crates/happenstance-testkit/tests/properties.rs — query_matches_agrees_with_a_naive_definition and is_violated_by_agrees_with_a_naive_definition — so a model that agrees with them is not agreeing with itself.

That sentence was false of this tree until phase 3 stage 5, and the next reader needs to be able to tell which side of that line they are on. Query::matches was constrained only algebraically — order-insensitivity, monotonicity, Query::all as the top element — and every one of those three is satisfied by a function that returns true unconditionally. is_violated_by had no property at all: three hand-written unit tests in happenstance-core and nothing else. The two oracle properties were written first, and deliberately so; a model whose grounding is a claim rather than a test is a second implementation of the contract, and two implementations that agree prove only that one author wrote both.

The rest of the model — ordering, the inclusive from bound, truncation, batch sequencing — is written out here rather than delegated, because those are the parts the store is being asked about.

§Symbolic position anchors

A generated ReadOptions::from(5) is meaningless against a store that assigns positions in steps of seven starting at 4096, and that store exists: GappedPositionStore in tests/mutation_coverage/variants.rs. So the generator never emits a position. It emits an Anchor — a description of a position — and the runner resolves it at execution against what the store has actually assigned so far.

This is CF-6 promoted from an assertion rule to a generation rule. The house rule says no assertion may name a literal position; a generator that emitted literals would satisfy the letter of that and violate all of it, by feeding the store inputs whose meaning depends on a policy the specification leaves free. Resolution happens once per operation and the resolved value is handed to both the model and the store, so the two can never disagree about which position was meant — only about what the store should do with it.

§This family carries its own enumeration, and its own emitters

CF-22 requires exactly one enumeration per rule family and forbids a second list of the same family. for_each_model_rule! is this family’s, and it lives here beside the rules it names rather than in suite.rs — cargo xtask spec-trace scans suite.rs for pub async fn, so a model rule written there would need a clause claiming it by name, and this is one macro rather than N named rules.

The emitters are duplicated for a smaller reason, stated so nobody consolidates it by accident: an emitter is invoked as emitter!(rule_a, rule_b, …) and the module path of the rules is baked into its expansion, not passed. Threading a path through would change a contract that three shipped emitters, three in-tree harnesses and CF-23 all depend on, to save eight lines. The alternative anyone tries first — re-exporting the model rules into crate::rules so emit_tokio finds them — is worse than duplication: it puts an unregistered name into the module no_orphan_rules scans, in the one blind spot that test documents (it cannot see a pub use).

§Feature and target gating

The whole module is behind the off-by-default proptest feature and not(target_arch = "wasm32"), so event_store_model_conformance! does not exist on the target where proptest does not build. An adapter that ships a wasm32 harness must gate its invocation the same way this crate’s own tests/memory_model_conformance.rs does. The mandatory wasm32 step of cargo xtask ci is what would otherwise find this.

Modules§

rules
The conformance rules of the model family.

Enums§

Anchor
A position named by description rather than by value.
Op
One generated operation against the store under test.