Module model
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.