Skip to main content

ProjectionFixture

Trait ProjectionFixture 

pub trait ProjectionFixture {
    type Store: ProjectionProbe;

    const SECOND_HANDLE: Capability = _;
    const RESET_REFUSAL: Capability = _;
    const COMMIT_FAULT: Capability = _;
    const REOPEN: Capability = _;

    // Required method
    fn connect(&self) -> impl Future<Output = Self::Store>;

    // Provided methods
    fn reopen(&self) -> impl Future<Output = Reopened> { ... }
    fn arm_commit_fault(&self) -> impl Future<Output = ()> { ... }
    fn protect_from_reset(&self, id: &ProjectionId) -> impl Future<Output = ()> { ... }
}
Expand description

One isolated projection store, plus the ways a projection rule is allowed to reach it.

Fixture’s sibling, and a second trait rather than a second associated type on the first, because Fixture::Store binds EventStore — the wrong port. An adapter may implement one of the two ports and not the other, and a single trait would oblige a projection-only adapter to invent an event store to satisfy a bound no projection rule reads.

Implement it for whatever a rule should be given a fresh instance of: a temporary directory holding a SQLite file, a connection pool aimed at a throwaway schema, a MemoryProjectionStore behind an Arc. Each instance is one store. Each connect is one handle onto it.

§Why Store is bound on the probe rather than on the port

ProjectionProbe is the write seam the suite drives an adapter’s read model through, and it is a supertrait of ProjectionStore — so one bound buys both. Binding the port instead would compile and would quietly buy a suite that cannot see a read model at all: with ProjectionStore alone, the only things generic code can do with a batch are commit it and roll it back, and the rule carrying this port’s entire reason for existing degenerates into a checkpoint test that a store writing only checkpoints passes.

Binding the probe here is what turns “your store must be observable” from a convention into a compile error: an adapter that has not implemented ProjectionProbe cannot name a type that satisfies this trait, so it cannot invoke the suite, and by CLAUDE.md’s rule it does not exist.

§No Send bound, and no trait_variant

The bare flavour, never SendProjectionStore: it is the weaker requirement and accepts both kinds of adapter, and only one of the two names may be in scope per module. Nothing ever spawns a fixture — the harness owns the executor — so the argument that gives the port two flavours (ADR-0001) does not reach here, and a second flavour would double the surface to buy a property no caller wants.

§Why the methods are spelled -> impl Future rather than async fn

Fixture’s reason, unchanged: async fn in a public trait fires rustc’s async_fn_in_trait lint and the gate runs -D warnings. The desugared form also puts the absence of + Send at the declaration, where a reader can see it. An implementation may still write async fn — the two are the same signature after desugaring, and the lint fires only on the declaration.

§Why Store is an owned associated type and not a GAT

The same rustc ICE Fixture records, for the same five ingredients, still reproducing on 1.97.1 (experiments/rustc-ice-gat-foreign-trait/). Hand back an owned handle holding a refcount; MemoryProjectionFixture is the worked example.

§Capability constants, and where an empty reason fires

Four constants, all answered deliberately: SECOND_HANDLE is a MUST, and RESET_REFUSAL, COMMIT_FAULT and REOPEN are the port’s genuinely declinable capabilities. A declined one must name a reason — Capability::declined rejects the empty string in a const fn assert! — but on an associated const that rejection arrives later than one would like. An associated const is evaluated lazily, only when monomorphised code reads it, which is after cargo check and cargo clippy have both stopped. It fails at codegen, so cargo build and cargo test catch it and cargo check and cargo clippy do not — a green check is not evidence here.

This is that failure, and reading the constant is the load-bearing line: a fixture nobody ever looks at compiles perfectly well.

ⓘ
use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};

struct Reasonless(std::sync::Arc<MemoryProjectionStore>);

impl ProjectionFixture for Reasonless {
    type Store = MemoryProjectionHandle;

    const SECOND_HANDLE: Capability = Capability::SUPPORTED;
    // The whole difference from the block below.
    const RESET_REFUSAL: Capability = Capability::declined("");
    const COMMIT_FAULT: Capability = Capability::declined(
        "this store cannot make a commit fail once it has been accepted",
    );
    const REOPEN: Capability = Capability::declined(
        "this store keeps everything in process memory, so a reopen has \
         no medium to read back from",
    );

    fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
        core::future::ready(MemoryProjectionHandle::new(std::sync::Arc::clone(&self.0)))
    }
}

fn main() {
    let _ = <Reasonless as ProjectionFixture>::RESET_REFUSAL;
}

The doctest above is spelled bare compile_fail, never compile_fail,E0080: rustdoc on 1.97.1 silently ignores an error-code annotation it cannot match, so the stricter-looking spelling is the weaker check (Capability::declined records the measurement).

Bare compile_fail passes when the snippet fails to compile for any reason, so the twin below is what makes the pair sound. It is the same snippet with one expression changed — the empty string becomes a sentence — and it must compile. A typo, a renamed item or a wrong path breaks the twin, and a broken twin is a hard test failure, so the only thing the pair can be reporting is the one expression that differs between them.

use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};

struct Reasoned(std::sync::Arc<MemoryProjectionStore>);

impl ProjectionFixture for Reasoned {
    type Store = MemoryProjectionHandle;

    const SECOND_HANDLE: Capability = Capability::SUPPORTED;
    const RESET_REFUSAL: Capability = Capability::declined(
        "this store holds no protection policy, so there is no projection it \
         could decline to reset",
    );
    const COMMIT_FAULT: Capability = Capability::declined(
        "this store cannot make a commit fail once it has been accepted",
    );
    const REOPEN: Capability = Capability::declined(
        "this store keeps everything in process memory, so a reopen has \
         no medium to read back from",
    );

    fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
        core::future::ready(MemoryProjectionHandle::new(std::sync::Arc::clone(&self.0)))
    }
}

let _ = <Reasoned as ProjectionFixture>::RESET_REFUSAL;

§Examples

The whole trait, over the reference store — this is what projection_store_conformance! is handed:

use std::sync::Arc;

use happenstance_core::MemoryProjectionStore;
use happenstance_testkit::fixtures::MemoryProjectionHandle;
use happenstance_testkit::{Capability, ProjectionFixture};

struct MyFixture(Arc<MemoryProjectionStore>);

impl ProjectionFixture for MyFixture {
    type Store = MemoryProjectionHandle;

    const SECOND_HANDLE: Capability = Capability::SUPPORTED;
    const RESET_REFUSAL: Capability = Capability::declined(
        "this store protects nothing, so it has no reset to refuse",
    );
    const COMMIT_FAULT: Capability = Capability::declined(
        "this store applies both halves of a commit under one lock and has \
         no write it can be made to fail between them",
    );
    const REOPEN: Capability = Capability::declined(
        "this store keeps its read model and checkpoints in process memory \
         only, so there is no medium a reopen could read them back from",
    );

    fn connect(&self) -> impl core::future::Future<Output = Self::Store> {
        core::future::ready(MemoryProjectionHandle::new(Arc::clone(&self.0)))
    }
}

Provided Associated Constants§

const SECOND_HANDLE: Capability = _

Whether this fixture can hand out a second, independent handle onto the one backing projection store.

This one is a MUST, as it is on Fixture, and for a sharper reason. PS-1 — the read-model write and the checkpoint write become durable together or not at all — is only observable from outside the connection that made the commit: a store whose commit is visible only to its own session satisfies every single-handle assertion and loses the row, or the checkpoint, or both, the moment anything else looks. So every rule in this family reads back through a fresh connect, and a fixture that cannot open one cannot observe the invariant this port exists for at all.

Declining it is therefore not a trade the suite may record as a skip — it is a fixture that does not meet the contract — and the type cannot tell the two apart, because both spell Capability.

§What enforces it

The rules themselves, through must! rather than require!, so the enforcement is on the path an adapter’s own CI executes. An adapter author who meets a red rule, writes const SECOND_HANDLE: Capability = Capability::declined("…") and re-runs gets a red rule again, quoting their own stated reason back at them — not a green suite and one SKIP line. The second line is mutation_coverage::projection_capability_skips_are_reported, which drives the whole enumeration against a fixture declining everything and asserts each of those rules rejects it.

It stays spelled as a Capability rather than as a bool so the failure carries the fixture’s own words.

§Why a MUST is nevertheless defaulted

Every capability on this trait is defaulted, this one included, and the default is a declension: a fixture that says nothing is read as having answered “no”, never as having answered “yes”. A default may decline on an author’s behalf; it may never declare on their behalf, because a declaration is a promise about a store only that store’s author is in a position to make.

Nothing about the MUST is weakened by that, because the compiler was never what enforced it. Requiredness bought an error[E0046] once, on the day an author wrote their impl; must! inside every rule of this family buys a red suite on every run, quoting the reason back, on the path an adapter’s own CI executes. The second is the stronger of the two and it is the one that was already there.

Silent in tests/projection_fixture_declension.rs holds both halves of that paragraph honest: it writes not one capability constant, so it stops compiling if any of the three goes back to being required, and it is rejected by commit_advances_the_checkpoint rather than skipped by it.

const RESET_REFUSAL: Capability = _

Whether this fixture’s store can be made to refuse a reset for a projection it protects.

The projection port’s one genuinely declinable capability, and a real trade rather than a fact: PS-18 makes refusal a mechanism the port supplies and leaves what to protect to the domain, so a store with no protection policy has nothing to refuse and declining is the honest answer. MemoryProjectionStore is exactly that store, and MemoryProjectionFixture declines with the real reason.

§The policy that used to be stated here, and why it was retracted

This constant was required rather than defaulted, unlike Fixture::MID_BATCH_FAULT, under a stated trait-level rule: a default would have to carry a testkit-written reason, and the projection family’s declension policy is that the fixture writes the reason — a store’s account of a trade only it can describe. The rule is retracted. Its argument is preserved above rather than deleted, because it is still the reason an adapter author should override this constant, and it is the cost the retraction accepts.

What it was measured against was the wrong precedent. The comparison it drew was to NO_CEILING_REASON, and CF-40 governs a fact — an Option<usize> ceiling, which that clause says MUST NOT be spelled as a Capability because None there is not a trade. The on-point precedent is CF-39, which governs MID_BATCH_FAULT: a genuine trade, of very nearly this shape, defaulted on its trait, whose default reason is written in the fixture’s own voice — and which recovers the honesty a default gives up as a clause-level MUST rather than as requiredness. A rule stated in one doc paragraph and contradicted by the specification’s treatment of its nearest neighbour is the thing that owed an argument.

The direct measurement of what requiredness buys runs the other way too. Fixture::REOPEN is required; NoopReopenFixture in experiments/suite-against-wrong-adapters/tests/support/wrong_fixtures.rs answers it, falsely, and scores better than an honest fixture that declines — 86 passed and 3 skipped against 83 passed and 6 skipped. Requiredness compels a sentence; it does not compel a true one.

So the default below is the testkit’s, and it says only what the testkit is in a position to know — that the fixture did not answer. An adapter author who leaves it standing has a SKIP line in their CI log written by somebody else, which is the whole of what this trade costs and is worth overriding to avoid.

It is read by exactly one rule, refused_reset_changes_nothing, which is PS-18’s; a fixture that declines it gets that rule as a reported skip carrying its stated reason, and a fixture that declares it must also override protect_from_reset, which is the mechanism this constant gates.

§What declaring it commits a fixture to

CF-43, CF-39’s shape for this capability: once protect_from_reset has returned, every later reset of that id through any handle answers ResetError::Refused, by a mechanism inside the store’s own reset that the fixture states; a store that refuses no reset declines. A forgotten override reaches the panic below. An override that does nothing is the quieter mistake, and refused_reset_changes_nothing rejects it at its first assertion, since a store nobody protected answers Ok: NoopProtectFixture, in this crate’s tests/projection_mutation_coverage/mutants.rs, is registered as failing it. happenstance-sqlite is the first adapter to declare the capability.

const COMMIT_FAULT: Capability = _

Whether this fixture can make a commit report failure.

PS-1’s second conjunct is a claim about a commit that failed: the read model and the checkpoint must be exactly as they were. Nothing a caller holds can make a conformant commit fail — that is the property under test — so, exactly as with Fixture::MID_BATCH_FAULT, the injection belongs to the adapter: a trigger that raises on the third row, a CHECK armed for one write, a connection killed between the read-model write and the checkpoint write. Every store that can do it does it differently, which is what makes it a capability rather than testkit machinery.

§Why it was required, and why it is now defaulted

Fixture::MID_BATCH_FAULT carries a default declension and this one deliberately did not, for RESET_REFUSAL’s retracted reason: a default has to carry a testkit-written reason, and this family’s declension policy was that the fixture writes it. “This store has no ceiling” is the same sentence for every store that says it, which is why NO_CEILING_REASON exists; why a particular store cannot make a commit fail is not — an in-memory map applies both halves under one lock, a one-shot HTTP backend has no interactive transaction to abort, and a pooled adapter usually can. The cost was one line per fixture and the return was that no fixture author was left un-asked.

That is still true, and it is still the reason to override this constant. What it is not is a reason to make it required, and this capability is the one where the difference is sharpest, because its nearest relative — MID_BATCH_FAULT, a trade of the same shape, over the same kind of adapter-supplied injection — was decided the other way in the specification, defaulted, with CF-39 carrying the honesty as a clause-level MUST. The section below is this port’s copy of that MUST, and it was already here before the default was: requiredness was never the thing holding this line.

§What declaring it commits the fixture to

failed_commit_leaves_both_unchanged arms the fault and requires the next commit to answer Err. A fixture whose arm_commit_fault does nothing would otherwise turn that rule into a green result about a store nothing ever faulted, which is CF-39’s argument one port over. So a store that can absorb every fault its fixture is able to arm MUST decline this capability with that as its stated reason, rather than declare it and contribute an Ok.

const REOPEN: Capability = _

Whether this fixture can be reopened: every outstanding handle’s process-level state discarded, so that a later connect observes only what was durably committed.

Fixture::REOPEN for the projection port, and CF-17 governs it in the same words: a fixture declaring it supported MUST make reopen discard that state over a medium that outlives the process’s hold on it, and MUST state the mechanism — which file is closed, which pool is drained. A fixture over a store with no medium outside the process MUST decline it, with that as its stated reason.

It is read by exactly one rule, committed_rows_and_checkpoint_survive_a_reopen, which reads PS-1’s durable across a reopen: until it existed, no projection rule showed that a committed read model and its checkpoint outlive every handle that wrote them. A store that keeps either half in process memory passes every other rule in the family, because every other rule reads back through a handle onto the same live process.

§Why it is defaulted, unlike Fixture::REOPEN

Every capability on this trait is defaulted to a declension, for the reason SECOND_HANDLE gives: a default may decline on an author’s behalf, never declare. A fixture that inherits this default is still told so, in its own CI, by [assert_projection_declensions_are_stated].

§What declaring it does not prove

What Fixture::REOPEN does not: an override that answers Reopened::Discarded over a volatile store and discards nothing is indistinguishable, through the port, from an honest reopen over a file. So the rule rejects a store that loses a commit across a reopen and cannot reject a fixture that only claims to reopen. The declaration MUST above is what carries that hazard, exactly as it does on the event-store side.

Required Associated Types§

type Store: ProjectionProbe

A handle onto this fixture’s backing projection store.

Bound on ProjectionProbe, which implies ProjectionStore — see the trait documentation for why the probe is the bound that earns its keep and the port is the one that does not.

Required Methods§

fn connect(&self) -> impl Future<Output = Self::Store>

Opens a handle onto this fixture’s backing store.

Async because a real fixture acquires its handle over I/O — a pool checkout, a connection, an HTTP client’s first request. A fixture whose connect is a refcount bump should return core::future::ready rather than an async move block, so it does not pretend to do I/O it does not do.

§Panics

Implementations panic rather than returning Result, for Fixture::connect’s reason and it is worth restating here rather than linking: a fixture that cannot connect is a broken test environment, not a non-conformant adapter, and a Result would put “the database is down” into the same channel as “the adapter is wrong” — where the suite’s own messages would then have to guess which one they were reading.

Provided Methods§

fn reopen(&self) -> impl Future<Output = Reopened>

Closes and reopens the underlying storage, discarding every outstanding handle’s process-level state, and says whether it did.

After an override returns Reopened::Discarded, a fresh connect must observe exactly what was durably committed and nothing else. Handles obtained before the call may stop working; a rule must not use one afterwards.

§The provided body says it reopened nothing

It returns Reopened::Nothing, and the rule asserts on that answer before it reads anything back. A fixture that declares REOPEN supported and forgets this override therefore fails on every run, with a message naming this method.

This is Fixture::arm_held_above_frontier’s shape rather than Fixture::reopen’s panicking provided body, and the difference is deliberate: an answer the rule asserts on puts the failure in the rule, where an adapter author’s CI reports it as that rule failing, and keeps a panic out of this crate’s library code.

fn arm_commit_fault(&self) -> impl Future<Output = ()>

Arms the store so that the next commit fails.

The fault fires once, and where inside the commit it fires is the adapter’s business: what PS-1’s second conjunct requires is that a commit which reported failure left the read model and the checkpoint exactly as they were, whichever half the store had got to.

§Panics

The provided body panics, for Fixture::arm_mid_batch_fault’s reason and with the same two ways of reaching it: a fixture that declares COMMIT_FAULT supported and forgets the override, or a rule that reached here without a gate. That is what stops “declared and never implemented” from passing vacuously — it aborts loudly instead.

fn protect_from_reset(&self, id: &ProjectionId) -> impl Future<Output = ()>

Puts id under this store’s protection, so the next reset of it is refused.

arm_commit_fault’s sibling, and it exists for the same reason: the capability above is a claim, and a rule cannot exercise the claim without telling the store which projection to protect. Nothing a caller holds can make a conformant reset answer ResetError::Refused — PS-18’s own words are that the port supplies the mechanism and the domain decides what to protect, so the domain is where the choice lives and a fixture is how a suite reaches it.

It takes the ProjectionId rather than declaring a protected one, which is the difference between a rule that can name its own subject and a rule that has to share one id with every other rule in the family. An adapter implements it however its policy is spelled: a row in a protected-projections table, a CHECK, a beforeDelete trigger, a hard-coded list.

This is not a fourth capability, and deliberately so. The projection family’s declension set is the three constants above; this is the mechanism the second of them gates, exactly as arm_commit_fault is the mechanism the third gates. A fixture that declines RESET_REFUSAL never has it called.

§Panics

The provided body panics, for arm_commit_fault’s reason and with the same two ways of reaching it: a fixture that declares RESET_REFUSAL supported and forgets the override, or a rule that reached here without a require!(F: RESET_REFUSAL) gate. “Declared and never implemented” then aborts loudly rather than passing vacuously — a fixture whose body did nothing would leave refused_reset_changes_nothing asserting about a store nothing had ever asked to protect anything.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§