A contract is the whole specification of one function

Its signature, the invariants that must hold for every input, and every edge case named, settled and argued for. Anything that satisfies it can replace anything else that does, which is what makes an implementation a detail.

A contract is 7 files, of which one is the implementation

The others are what judges it. All of them are readable before you install anything, and all of them are served at the contract’s own address, so a copy of the harness can be checked against the definition and then run against any implementation.

• contract.ts

  The declaration itself: what the function is for and what it is not for, the four universal properties answered one by one with a reason each, how many draws a property test takes and the measurement that chose that number, and the shapes an implementation is timed on.

• signature.test-d.ts

  The signature, checked as types rather than read as prose. It is compiled against assertions written beside it, so a widened parameter or a lost generic is a failing build and not a line in a changelog.

• properties.test.ts

  The invariants that must hold for every input, generated and re-seeded on every run rather than fixed. Where a universal property does not apply, the contract says so and says why, instead of shipping a test that cannot fail.

• edge-cases.ts

  Every settled case as data: the input, the answer, a frozen identifier a reader can link to, and the argument for why that answer and not another. A grammar has no axioms to rest on, so this table is what the contract rests on instead.

• edge-cases.test.ts

  The replay of that table against the implementation shipped beside it. The declaration above is what a client reads; this is what makes it true of the code, and neither stands in for the other.

• profiles.test.ts

  The benchmark profiles, run to prove the samples are the shapes they claim to be. There are no timings until there is a reference machine, and the profiles exist so that two implementations are compared on the same work when there is.

• reference.ts

  The implementation, and the only one of the seven that is a detail. It is the file the command copies into your project, and anything that satisfies the other six can replace it.

A published contract is frozen for life

Frozen for the life of its major version, and almost everything it settles is an address that can never move: a case that was published is a case a reader can link to for as long as the major exists. That is a heavier promise than a version number, and it is why a contract is written in full and measured before it is published — including the ones that are then turned down.

An implementation freezes nothing

It competes under a contract that already exists, and that contract’s own suite — public, and runnable by anyone — is what decides between it and ours. An implementation the registry stops recommending goes on being served, so the opinion changes what is suggested and never what is reachable: a project that installed it keeps resolving its digest.

What a contribution can be

An implementation, or an input where ours is wrong — never a contract. Because a contract is frozen and almost everything it settles is an address that can never move, it is ours to keep rather than yours to send. CONTRIBUTING.md in the repository says what can be received today and what cannot.

Not every field is checked the same way

A contract is a record, and each of its fields carries the stratum it is verified at — so you are told which sentences no run could falsify instead of being left to assume they were all checked. That table is on the method page, field by field: how we verify, and what it does not prove.