# Contract glossary

> The vocabulary of the SDK contract model — every term is a standard industry name, and each entry names the spec, book, or product it comes from.




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](https://www.rfc-editor.org/rfc/rfc2119) 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](https://developers.kismet.travel/telemetry/contract.md), 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](https://semver.org/). 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](https://www.rfc-editor.org/rfc/rfc2119);
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](https://developers.kismet.travel/sdk/contracts.md) for the levels, and
`docs/adr/0001-one-contract-defined-in-the-sdk.md` in the repository for why
there is no fourth level.