model-a-protocol

Installation
SKILL.md

Model a protocol

A protocol is a set of steps that share state, such as a request, a background delivery, a sweep and an erase on one record. Example tests run one order of those steps. A model checker runs every order within small bounds, including a crash between any two steps. It finds interleaving bugs that reading and example tests miss.

The worked example is the join-intake model in packages/core/spec/. Its README.md shows each part of this skill on real code. Its test is packages/core/test/join-intake-spec.test.ts.

When to model

Model a protocol when its steps can interleave or stop halfway:

  • A crash can land between two writes.
  • A retry re-sends after an unknown outcome.
  • An alarm, a cron sweep, or waitUntil finishes work the request started.
  • Two writers can change one record.

Model it before the design review, so reviewers argue over a trace instead of prose. A pure fold, a read path, or a single atomic write does not need a model. Use a property or a model test for those.

A fix to a protocol that has no model does not wait for one. Land the fix with its failing-then-passing test.

Installs
2
GitHub Stars
214
First Seen
8 days ago