Specs as Laws
Given, When and Then propositions with their quantifiers and proofs

In July 2020, Behavior Specs' Specs set out how a dashboard for covidsim.team would be specified as it went from one developer to a public health team: user stories first, then Given, When and Then scenarios, with personas such as a data officer who uploads a file every day. Two of its sentences carry more than they seem to. One says that the modules with these specifications only do what the specs say, "nothing more, nothing less". The other lists the connectives a spec may need, and, or, not, with, put, once and never, and notes that Gherkin permits only a few of them.
Nothing more and nothing less is a law, and once and never are the two words this series has spent the most care on. Row 12 of my 2014 research matrix asks that "matrix concepts and libraries should behave the same in theory and practice regardless of context", and I read that as an order of work: the law first, the code after, and every law checked. When practice teaches us something, we amend the law and record when we did.
This post is that order of work, in TypeScript, with every checker written from scratch so nothing stands between the law and the code that tests it.
A spec is a law with its quantifiers hidden
A behavior spec reads like an example:
Given Asha shares her readings with her clinic in bands, When she writes a reading of 142 mg/dL, Then the clinic's copy holds a band row and no reading.
Read it again and it is a claim about every reading, every share and every clinic, written about one of each. The example is a witness. The law under it is:
For every reading r and every share in bands, the rows the clinic receives for r are one row of kind
view:glucose_bandand nothing of kindglucose.
Once a spec is read that way, testing it means generating many readings and many shares and checking the law on each, which is property-based testing. Claessen and Hughes introduced it with QuickCheck in 2000. The checker is short enough to write here, and writing it keeps every choice in view.
// laws.ts
export interface Rng {
next(): number;
int(low: number, high: number): number;
pick<T>(items: readonly T[]): T;
}
/** Mulberry32: enough for picking test inputs, and never for anything secret. */
export function seeded(seed: number): Rng {
const s = { state: seed >>> 0 };
const next = () => {
s.state = (s.state + 0x6d2b79f5) >>> 0;
const a = Math.imul(s.state ^ (s.state >>> 15), s.state | 1);
const b = a ^ (a + Math.imul(a ^ (a >>> 7), a | 61));
return ((b ^ (b >>> 14)) >>> 0) / 4_294_967_296;
};
const int = (low: number, high: number) => low + Math.floor(next() * (high - low + 1));
return { next, int, pick: (items) => items[int(0, items.length - 1)]! };
}
export type Gen<T> = (rng: Rng) => T;
export const tuple = <T extends unknown[]>(...gens: { [K in keyof T]: Gen<T[K]> }): Gen<T> =>
(rng) => gens.map((gen) => gen(rng)) as T;
/** Checks `law` on `runs` inputs drawn from `gen`, and names the seed and the input when it fails. */
export function forAll<T>(gen: Gen<T>, law: (input: T) => boolean, { seed = 1, runs = 500 } = {}): void {
const rng = seeded(seed);
for (const run of Array.from({ length: runs }, (_, i) => i)) {
const input = gen(rng);
if (!law(input)) throw new Error(`law failed at seed ${seed}, run ${run}: ${canonicalJson(input)}`);
}
}
The seed matters more than it looks. The same seed makes the same inputs on every machine, so a failure is named by its seed alone, and anyone can replay it.
Small sets, on purpose
The first law the series relies on is that merges are joins: commutative, associative and idempotent. Here are the three, over copies of one setting edited on several phones:
const same = (a: unknown, b: unknown) => canonicalJson(a) === canonicalJson(b);
// Stamps from a small set, so equal stamps and near-equal ones come up in most runs.
const stamp: Gen<string> = (rng) =>
rng.pick([
'1790000000000.0000.phone-a',
'1790000000000.0001.phone-a',
'1790000000000.0000.phone-b',
'1790000000001.0000.phone-c',
]);
const copy = (rng: Rng) => ({ key: 'language', value: rng.pick(['"en"', '"ne"']), stamp: stamp(rng) });
forAll(tuple(copy, copy), ([a, b]) => same(join(a, b), join(b, a)));
forAll(tuple(copy, copy, copy), ([a, b, c]) => same(join(join(a, b), c), join(a, join(b, c))));
forAll(copy, (a) => same(join(a, a), a));
The generators draw from tiny sets, and that is the most useful decision in the file. A generator that draws stamps from all of time almost never produces two equal stamps, so the tie, which is where merges break, comes up once in a million runs. Drawn from four stamps and two values, two copies with the same stamp and different values come up in most runs. A merge that keeps the first of two copies with equal stamps passes a test over random stamps and fails this one within a dozen runs, with the seed and the two copies printed.
The real merge laws in the systems I build run the same way, over settings, reminders and answers, with two kinds of stamp that do not parse thrown in, because old rows have no stamp at all. Then they run once more through the real export and restore: two phones edit in generated orders at generated times, each restores the other's backup, and both must end with the same settings. A law that holds on the function and fails on the path the function sits in has not been checked.
The laws worth writing first
Not every law earns a generator. These are the ones the matrix series leans on, roughly in the order I write them for a new piece of the substrate.
- Merges are joins: the three laws above, for every kind of state that can be edited in two places.
- Order independence: feed a log the same rows in any order, in any batches, any number of times, and it ends in the same state. Suggestions from Papa checks this for its log on every build.
- Round trips: a translation out and back gives the record we started with; a backup exported and restored gives the same rows, byte for byte.
- Rebuilds: an index dropped and rebuilt from the rows is byte for byte the index that was written as rows arrived.
- Views: every row a peer receives is what the view says that peer may see, and nothing else. The band spec above is one case.
- Determinism: the same module, given the same event, gives the same output on every host, checked against vectors written down once.
The first four are algebra. The fifth is about who sees what, which is where personas come in.
Personas are parties
The 2020 post used personas to break stories down, and in the matrix a persona has a precise meaning: a party, with its own keys, its own log and its own view of everyone else's rows. "As a patient" and "as a clinician" name two boxes, and a spec that names both is a spec about the wiring between them.
That turns the band spec into a law over a pair of parties:
const reading = (rng: Rng) => ({ kind: 'glucose', mgdl: rng.int(20, 600) });
forAll(reading, (r) => {
const asha = party('asha');
const clinic = party('clinic');
share(asha, clinic, bandView(BANDS));
asha.write(r);
sync(asha, clinic);
const seen = clinic.rowsFrom(asha);
return seen.length === 1 && seen[0]!.kind === 'view:glucose_band' && !seen.some((row) => row.kind === 'glucose');
});
The persona that used to be a sentence at the top of a story is now a key in a test, and the story's "so that" clause has become the property after return.
Once, never and not
The 2020 list of connectives reads well as a type system. And, or and with are positive: a spec built from them is monotone, and any party that holds the records can check it without asking anyone. Put is the idempotent write, a record put at its own id, which changes nothing the second time. Not is the one that needs care, because a record that has not arrived yet can make it false; a spec with not in it is checked where the record can still be stopped, or settled by co-signature, as the constraints section of Mathematics' Architecture & Processes explains. Once is linear: a slot that can be taken once is a type the compiler holds to, and that same post has the Idris that refuses a slot spent twice. Never is a fence, a statement about what must not exist anywhere, checked over everything the code declares, and the fences section below comes back to it.
Gherkin has no word for once or never, so here they live in types and in fences.
Failure is a scenario too
Behavior Specs' Specs began by asking software to "plan for failure", and a spec plans for failure by writing it down. Every scenario gets a second outcome: what must hold when the step works, and what must hold when it does not, because the step was refused, the device went offline or the app crashed halfway.
// scenario.ts
/** A scenario names its failure too: what must hold when the step works, and what must hold when it does not. */
export interface Scenario<S, A> {
readonly given: (s: S) => boolean;
readonly when: A;
readonly then: (before: S, after: S) => boolean;
/** Refused, offline or crashed: nothing the person signed is lost, and the failure is visible. */
readonly otherwise: (before: S, after: S) => boolean;
}
For the upload in the 2020 post, otherwise says the file stays selected, nothing is half written, and a failure is shown with its reason. Over a log, most of that comes free: a row is either signed and appended or it is not there at all, so a crash leaves no half-written row, and the cursor resumes from the last row that landed.
Offline gets a law of its own, because it is the failure every party has every day. The same writes, made on two devices with the link cut at random, must end where one device would have ended once the link heals:
// offline.ts
/** What the link carries both ways: each log gets everything the other holds. */
const exchange = (logs: readonly Log[]) => logs.forEach((a) => logs.forEach((b) => a.append(b.rows())));
forAll(tuple<[Row[], boolean[]]>(rowsGen, cutsGen), ([rows, cuts]) => {
const [a, b, one] = [createLog(), createLog(), createLog()];
rows.forEach((row, i) => {
(i % 2 === 0 ? a : b).append([row]);
one.append([row]);
if (!cuts[i]) exchange([a, b]); // the link is up after this write
});
exchange([a, b]); // the link heals
const ids = (log: Log) => log.rows().map((r) => r.id).join();
return ids(a) === ids(one) && ids(b) === ids(one);
});
rowsGen draws rows from a handful of times and ids, so equal times and rows written on both sides come up often, and cutsGen cuts the link after about half the writes. The law holds over the log in Suggestions from Papa, and it is the screen-sized version of the interplanetary case in the seventh section of Mathematics' Architecture & Processes.
Nothing more, nothing less
"Nothing more, nothing less" is two laws. Nothing less is what the property tests check: every scenario a spec allows can happen, and happens as the spec says. Nothing more is a closed world, and it is cheapest as a guard at the one place a module can change anything, the append. A module may append a row only if some spec for that kind of row, co-signed by everyone the spec names, allows it:
// closed.ts
/** A spec as the code holds it: the kind of row it covers, the transitions it allows, and who must co-sign it. */
export interface Spec {
readonly id: string;
readonly kind: string;
readonly signers: readonly string[];
readonly allows: (log: readonly Row[], row: Row) => boolean;
}
/** Nothing more: a row is admitted only if a spec for its kind, co-signed by everyone it names, allows it. */
export function admits(specs: readonly Spec[], cosigned: (specId: string, key: string) => boolean, log: readonly Row[], row: Row): boolean {
return specs.some((s) => s.kind === row.kind && s.signers.every((key) => cosigned(s.id, key)) && s.allows(log, row));
}
A row of a kind no spec covers is refused, and so is a row whose spec is still waiting for the customer's signature. The specs are records like everything else, co-signed by the customer and the developers, so changing what a module may do is one more co-signed addition, and the history of what it was allowed to do, and when, stays readable.
Doors and The Room
The strongest spec I know for an app is that every way into it does the same thing. A person reaches an app through its screens. More and more often, an agent reaches it through a command line or a set of tools, on that person's behalf. If the two doors lead to different rooms, the person and their agent are using different apps under one name.
This autumn I opened a talk with "Our products get to program all of us. We should all get to program our products." A command line that does exactly what the screens do is the plainest form of the second sentence. It is also a claim that can be tested, and the theorem the test stands on is congruence, which Unified Computations quotes from my paper: two boxes that are bisimilar give collaborations that are bisimilar. The screen and the command line are two boxes over one state. Drive both with the same random steps and compare their states after every step, and you are checking that they are bisimilar on the runs you tried.
// differ.ts
export interface Step {
readonly action: string;
readonly args: Record<string, string | number>;
}
/** One way into the app: its screens, its command line, an agent's tools. */
export interface Door {
apply(step: Step): Promise<'done' | 'refused'>;
/** The app's state, canonical, with every time inside the run's window made equal. */
state(): Promise<unknown>;
}
export type Run = { readonly ok: true } | { readonly ok: false; readonly at: number; readonly why: string };
/** Plays `steps` through two doors from the same start, and stops at the first step after which they differ. */
export async function differ(open: () => Promise<[Door, Door]>, steps: readonly Step[]): Promise<Run> {
const [a, b] = await open();
for (const [at, step] of steps.entries()) {
const [ra, rb] = [await a.apply(step), await b.apply(step)];
if (ra !== rb) return { ok: false, at, why: `${step.action}: one door ${ra}, the other ${rb}` };
const [sa, sb] = [canonicalJson(await a.state()), canonicalJson(await b.state())];
if (sa !== sb) return { ok: false, at, why: `${step.action}: the states differ` };
}
return { ok: true };
}
A refusal is compared too. If the screen refuses to delete the last item and the command line deletes it, the two doors differ at that step, even if their states happen to agree afterwards.
A failing run of thirty random steps is hard to read, so the checker shrinks it. It drops chunks of steps while the run still fails, halving the chunk each pass, and keeps the shortest sequence it finds:
/** Drops chunks of steps while the run still differs, halving the chunk each pass; returns the shortest found. */
export async function shrink(open: () => Promise<[Door, Door]>, steps: readonly Step[], failed: Extract<Run, { ok: false }>, budget = 60) {
type Best = { readonly steps: readonly Step[]; readonly run: Extract<Run, { ok: false }> };
/** One pass at one chunk size, from the end: drop each chunk, and keep any shorter run that still differs. */
const pass = async (best: Best, size: number, from: number, tries: number): Promise<[Best, number]> => {
if (from < 0 || tries >= budget) return [best, tries];
const candidate = [...best.steps.slice(0, from), ...best.steps.slice(from + size)];
if (candidate.length === 0) return pass(best, size, from - size, tries);
const run = await differ(open, candidate);
return pass(run.ok ? best : { steps: candidate.slice(0, run.at + 1), run }, size, from - size, tries + 1);
};
/** Passes at halving sizes, down to single steps. */
const sizes = async (best: Best, size: number, tries: number): Promise<Best> => {
if (size < 1 || tries >= budget) return best;
const [after, used] = await pass(best, size, best.steps.length - size, tries);
return sizes(after, size === 1 ? 0 : Math.max(1, size >> 1), used);
};
const start: Best = { steps: steps.slice(0, failed.at + 1), run: failed };
return sizes(start, Math.max(1, start.steps.length >> 1), 0);
}
On a toy list app whose command line removes the wrong item when the list holds exactly three, seed 2 fails at its fifteenth step, and the shrinker reports add add add remove: the four steps that matter, with the seed to replay them.
Two details made this practical. The state each door reports is canonical, the same canonical JSON the signatures use, with every time inside the run's window made equal, so two doors that wrote the same row a millisecond apart are not reported as different. And the tables an app keeps for its own bookkeeping, its usage counts and its logs, are set aside by name, since a screen counts its own use and a command line counts nothing.
The same checker works on the shared document in Suggestions from Papa. Its Svelte version and its ReactiveScript version are two doors over one log: give each a driver that turns a step into clicks and keystrokes, run them side by side, and compare currentOf(log.rows()) after every step. Two frameworks, one law.
A ratchet
A new action in an app has no driver for the screen on the day it is written, and a checker that silently skips it is a checker that covers less every week. So the actions the checker does not drive yet are listed by name, and a coverage rule holds the list honest:
// ratchet.ts
/** The actions with no driver yet. This list only shrinks. */
export const NOT_YET: readonly string[] = ['posts.reshare', 'backup.export', 'backup.restore' /* … */];
export function coverageProblems(registry: readonly string[], driven: ReadonlySet<string>): string[] {
const problems: string[] = [];
for (const action of registry) {
const listed = NOT_YET.includes(action);
if (!listed && !driven.has(action)) problems.push(`${action} is neither driven nor listed`);
if (listed && driven.has(action)) problems.push(`${action} is driven now: take it off the list`);
}
return problems;
}
An action that is neither driven nor listed fails the build, so nothing new arrives unchecked. An action that gains a driver and stays listed fails too, so the list cannot hold stale entries. The list only shrinks.
Fences
Some laws are about what must never exist, and those are checked without running anything. The fence in Unified Computations scans imports, so the app reaches its sync layer through one door only. The fence in Mathematics' Anarchitecture & Processes walks the graph of features, so no chain of them turns a reading into a dose without a clinician's signature. Both run in CI beside the property tests, and both print what they found by name, the file and the import, or the chain of features.
A fence is a law whose quantifier is never. It is checked exhaustively over what the code declares, which is a stronger check than any number of generated runs, and it is the reason I keep the set of kinds, roles and views closed: a closed set is one a fence can walk.
Proved, tested, fenced
That leaves three kinds of law, and each gets the check it can bear.
The model is proved. The paper's theorems, congruence, order independence and gluing among them, are checked by Lean, once, for every schedule and every number of parties. Nothing about them needs to run again.
The merge laws this post tests are small enough to prove on a model as well. Order the copies totally by their stamp, with the copy's bytes as the last tie-break, and a merge keeps the greater; on that model the three laws, and the two facts the sync depends on, compile against Lean's standard library:
namespace Socioware
/-- The model of a merge: copies ordered totally by their stamp (wall time, counter, device,
then the copy's bytes), so merging two copies keeps the greater. -/
def join (a b : Nat) : Nat := max a b
theorem join_comm (a b : Nat) : join a b = join b a := Nat.max_comm a b
theorem join_assoc (a b c : Nat) : join (join a b) c = join a (join b c) := Nat.max_assoc a b c
theorem join_idem (a : Nat) : join a a = a := Nat.max_self a
/-- Copies merged in any order give the same result: any permutation of the arrivals. -/
theorem fold_perm {xs ys : List Nat} (h : xs.Perm ys) (start : Nat) :
xs.foldl join start = ys.foldl join start := by
induction h generalizing start with
| nil => rfl
| cons x _ ih => exact ih _
| swap x y l =>
simp only [List.foldl_cons]
congr 1
simp only [join]
rw [Nat.max_assoc, Nat.max_comm y x, ← Nat.max_assoc]
| trans _ _ ih₁ ih₂ => exact (ih₁ _).trans (ih₂ _)
/-- And a copy that arrives twice changes nothing. -/
theorem fold_dup (start x : Nat) (xs : List Nat) :
(x :: x :: xs).foldl join start = (x :: xs).foldl join start := by
simp only [List.foldl_cons]
congr 1
simp only [join]
rw [Nat.max_assoc, Nat.max_self]
end Socioware
fold_perm is the statement the property tests sample: any permutation of the arrivals gives the same state. The proof covers every permutation of every list; the tests check that the TypeScript join is the function the proof is about.
The code is tested. Property tests and the differential checker run the laws over generated inputs, small sets on purpose, seeds named, failures shrunk. They are evidence, never proof, and they are cheap enough to run on every change.
The architecture is fenced. Imports, features and vocabularies are walked exhaustively, because what must never exist cannot be sampled.
Row 12 asked that the socioware behave the same in theory and in practice. In this order of work the theory is written first and the practice is held to it by the cheapest check that can hold it. When the two disagree, one of them is wrong, and finding out which is the most useful thing a test can do.
Given, When and Then were always a law with its quantifiers hidden. Writing the quantifiers down is the whole method.
Readings
- Risav Karna, Behavior Specs' Specs (2020).
- Koen Claessen and John Hughes, "QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs" (2000).
- Andreas Zeller and Ralf Hildebrandt, "Simplifying and Isolating Failure-Inducing Input" (2002).
- William McKeeman, "Differential Testing for Software" (1998).
- Dan North, "Introducing BDD" (2006).
- Robin Milner, Communication and Concurrency (1989).
- Risav Karna, Collaboration Is Composition (2026).
About the author
- Technical Leadership & Architecture
Comments
Join the discussionThe useful move is to read a Given, When and Then example as a law with its quantifiers hidden: one reading and one share stand in for every reading and every share. That turns the check into generating many inputs and testing the law on each, rather than stopping at the example. Writing the checker from scratch, with a named seed so a failure can be replayed on any machine, keeps that path in view. The closing point is fair: property tests are evidence, never proof, and when theory and practice disagree, finding out which is wrong is the most useful thing a test can do.
An Architecture
In this series, we explore ways to think about the architecture of common libraries & UIs. We will use JS, Bun, TS, Svelte 5+, Nx, RxJS, ScalaJS, ReasonML, Idris 2+, and Lean 4+.





