1@README.md
2
3## Notes for agents
4
5- **The suite is the specification.** If a contract in `whiskers-ports` changes, its law changes here in the
6  same commit and every adapter is held to the new one. Do not weaken a law to make an adapter pass; fix the
7  adapter, or change the contract deliberately.
8- **Prove the suite can fail.** `src/lib.rs` has adapters that are each wrong in one way the contracts forbid
9  (overwrites instead of merging, ignores the cursor, forgets outstanding reservations, reports a change every
10  time) and tests that the matching law panics. Add one when you add a law.
11- **Keep it wasm-clean and runtime-free.** No threads, files or clocks: laws are synchronous and drive futures
12  with `whiskers_ports::run_ready`. Concurrency that needs real threads (two requests at once on the native
13  adapter) is tested in the adapter's own crate, because the observable consequence of atomicity is also
14  stated sequentially here (two appends at one cursor take one).
15- **A law is selected by capability.** A new law set gets a fixture trait and a `Suite` method in `suite/fixture.rs`, added to
16  `Fixtures` and `Suite::complete`; the in-memory harness (`MemFixtures`) and every adapter's own harness get the fixture, or fail
17  to compile. Never make a law that "skips" when the adapter lacks its port: the method does not apply, that is the mechanism.
18  A law that only some harnesses can run (the chat hub's write fault) is its own fixture and method, not an `Option`.
19- A law function takes `fresh: &impl Fn() -> A` and `restart: &impl Fn(A) -> A`; `restart` must reopen the same
20  storage, as a process restart would.