Contract glossary

This glossary deliberately borrows every name from a spec, a book, or a product that already owns it. When a name below replaces an earlier Kismet-only word, the entry says so.

Contract

A contract is the set of necessary behaviors a component needs to serve a guest. How you build them is up to you. It can also recommend behaviors (SHOULD) and rule some out (MUST NOT). Requirement levels come from RFC 2119 and are defined by consequence; the catalog is defined once, in the SDK.

The standard names

Term	Source	What it means here
Critical path	Project scheduling (CPM, Kelley & Walker)	The ordered set of contracts a page cannot ship without. Replaces an earlier in-house word.
Parallel change (expand → migrate → contract)	Martin Fowler	How the catalog itself migrates: add the new shape, move consumers, remove the old — never a breaking flag day.
Shim	Industry usage (software compatibility layer)	A generated old-format catalog kept so existing consumers keep working while they migrate. Replaces an earlier in-house word.
Substitution	Liskov & Wing, 1994	The swap rule: any implementation meeting a contract’s requirements can replace any other.
Documented deviation	RFC 2119 §6	The recorded, visible justification for not meeting a SHOULD.
Normative vs informative	WAI-ARIA 1.2 (normative) vs WAI-ARIA Authoring Practices Guide (informative)	Contracts are normative — testable and enforced. Recipes are informative patterns — how you usually build, not what you must.
Precondition surface	Design by Contract, Meyer 1992	The props and data an implementation needs up front (ContractProps).
Postcondition families	Design by Contract, Meyer 1992	The must.* requirement families — what holds after render and interaction.
Invariants	Design by Contract, Meyer 1992	The mustNot entries — true in every state. We take the vocabulary only; checks run on the rendered page, not in a runtime assertion framework.
Test mode	Stripe (test mode vs live mode)	The fixture data mode: deterministic local data, no promotion path to production. Replaces “fixture data mode” as the generic name.
Strangler fig	Martin Fowler	The customization ladder in one pattern: swap piece by piece behind a stable seam — here, the contract.

Distinctions that stop overloaded words

Capability contract vs tracking plan. A capability contract (this glossary’s subject) states requirements for one guest-facing capability. A tracking plan is the analytics artifact that names events, properties, and their semantics — the sense of the document published at Tracking contract v1.0, which uses RFC 2119 for its wire rules. Same capital-words convention, different kind of document: one governs rendered guest capabilities, the other governs emitted events. Renaming that document’s title is planned separately; until then, read “tracking” there as tracking plan.

Certified implementations list vs implementation source map. The certified implementations list says which implementations pass the conformance suite for a contract version — a quality statement. The implementation source map says where a contract’s implementation code lives — a navigation statement. Neither implies the other.

Entities vs contracts. Data types and DTOs are entities (domain-driven design usage). @kismet-tech/sdk/contracts currently re-exports them for compatibility; that subpath is a Props-shaped legacy surface and its rename is deferred, not cancelled.

Contract versioning

Contracts use semantic versioning. A major version bump happens when a MUST is added or removed; adding or tightening a SHOULD is minor. Certified keys pin a major version only, so minor additions never break a certification.

Requirement levels

MUST, SHOULD, MUST NOT come from RFC 2119; their per-contract placement is normative. Anything unsaid is MAY by omission. A MUST is only real if code enforces it: every MUST and MUST NOT names a registered check that a runner evaluator implements, and the contract lint fails otherwise — an unenforceable rule is a SHOULD, not a MUST. See What is a contract for the levels, and docs/adr/0001-one-contract-defined-in-the-sdk.md in the repository for why there is no fourth level.