Loose vocabulary is how software teams end up shipping four things when they thought they were shipping one.
A recurring source of confusion in this category is that four different things share the word calculator. Product managers scope one, engineers build another, compliance reviews a third, and marketing writes about a fourth. The result is a project in which every stakeholder is correct about their piece and none of them are talking about the same object. The vocabulary below is what Worthune uses across every doc, spec, changelog entry, and article. It is not the only defensible vocabulary. It is a defensible one, applied consistently.
The four terms
A calculator is a user-facing interface that accepts inputs and displays outputs. It is what a customer sees. A calculator has fields, labels, validation messages, a submit button, and a place where the answer appears. A calculator does not, by itself, contain math. Two products can ship the same calculator on top of two different models, and the users will not know.
A model is a named, versioned computation. It has a spec. It has an input schema and an output schema. It has assumptions. It has a version number. When a product manager says the retirement calculator is wrong, the actionable claim is almost always about the model, not the calculator. Fixing the calculator changes what the user types. Fixing the model changes what comes back.
An engine is the runtime that executes a model given valid inputs. It is code. It has performance characteristics, error handling, and infrastructure dependencies. An engine without a model computes nothing. A model with no engine is a document. The pair — model plus engine — is what produces a number.
A spec is the human-readable contract for a model. Inputs, ranges, formula, assumptions, exclusions, sourced constants, and versioning rules all live in the spec. A spec is normative, which means the engine is graded against it, not the other way around. If the engine produces a number the spec does not authorize, the engine is wrong. If the spec authorizes a number that is not what the product wants, the spec gets amended and a new version ships.
| Term | What it is | What it is not |
|---|---|---|
| Calculator | A user-facing UI that accepts inputs and displays outputs | The math itself |
| a calculator without a model is a form. | ||
| Model | A named, versioned computation with a published spec, defined inputs, and defined outputs | A codebase. A model may be implemented many times. |
| Engine | The runtime that executes a model given valid inputs | A model. An engine without a model computes nothing. |
| Spec | The human-readable contract for a model | Documentation. A spec is normative |
| docs describe. |
Why the distinction is load-bearing
When someone reports that the calculator is wrong, ask which artifact is wrong. If the UI mislabels an input, that is a calculator bug and the fix is a copy change. If the formula produces the wrong answer for correct inputs, that is a model bug and the fix is a spec amendment plus a new engine release. If the runtime rounds inconsistently across environments, that is an engine bug and the fix is code. If the assumption was never written down anywhere, that is a missing spec, and the fix has to start there before anyone touches code.
The consequence of skipping this triage is a class of bug that lives forever. Someone patches the calculator to display a warning. Someone else patches the engine to clamp an input silently. A year later the two patches interact in a way nobody predicted, because the underlying spec was never revised to admit the edge case. Verified computation depends on the spec being the single source of truth. Every other artifact is graded against it.
Related terms
A contract is the machine-readable subset of a spec — input JSON schema, output JSON schema, error codes. A contract is what an API consumer reads to know what to send and what to expect. A spec is what a domain expert reads to know why.
A constant is a value the model reads from the facts registry, never hard-coded. Constants are named. Every reference to a constant in a spec resolves to a registry row with a source URL and a revision date. A constant that is not in the registry is not a constant; it is a magic number, and magic numbers are how calculators age.
An envelope is the response object returned by a model call. It contains the outputs, the spec version that produced them, the list of constants used with their revision dates, and a SHA-256 hash of the full envelope. Storing the envelope is what makes an answer auditable later; storing only the outputs is what makes an answer a rumor.
A verification case is an input-output pair used to prove two implementations of the same spec agree. Verification cases are code, checked into version control, run on every release. A model with fewer than a hundred verification cases has not been verified in any meaningful sense; a model with several hundred has been, and can produce the passing log on demand.
- Contract — the machine-readable subset of a spec.
- Constant — a value read from the facts registry, never hard-coded.
- Envelope — outputs plus specVersion, factsUsed, and record.sha256.
- Verification case — an input/expected-output pair used to prove two implementations agree.
Using the vocabulary
In practice, the vocabulary shows up in three places. In tickets: bugs are filed against a specific artifact, not against the calculator as a whole. In changelogs: a model version bump is separate from an engine release, and both are separate from a calculator redesign. In customer support: the answer to where does this number come from resolves to a spec URL, not to a screenshot of the UI.
The vocabulary is not the point. The point is that once the four terms are separate, the conversations about correctness become answerable. The alternative — one word for four things — is how a team spends a quarter arguing about a calculator and ships nothing verifiable at the end of it.
A worked example
Suppose a user reports that the refinance calculator says a break-even of thirty-one months, and the user's own math says twenty-eight. Four different investigations resolve four different bug classes. If the calculator UI is echoing the wrong output field — displaying total-interest-saved as break-even-months — the fix is a template change. If the model is applying closing costs before rate reduction rather than the other way around, the fix is a spec amendment plus a version bump. If the engine is rounding intermediate values differently than the spec prescribes, the fix is engine code and a new regression test. And if the spec does not say how closing costs interact with points, the fix begins with a spec revision, followed by a new implementation and new verification cases.
Without the four-term vocabulary, the ticket reads calculator is wrong and gets triaged as whichever kind of bug the assigned engineer is most comfortable fixing. With the vocabulary, the ticket reads model spec ambiguity in refinance closing-cost interaction and gets routed to the person who owns the spec. The triage cost drops by more than the vocabulary cost.
Sources
- [1] Worthune model spec index. https://worthune.com/docs