# Public vocabulary contract: [PACKAGE ID]

> Team document template. Copy this file, fill every bracketed field, and
> store the result beside the vocabulary package it describes. The engine
> never reads this file: it records the stability promises the team makes
> to consumers, not a package format.

How to use: one contract per shared vocabulary package (a package that
declares entities, relations, enums, and constants for others to import,
with no rules and no source text inside). Consumers read this before they
import; owners update it before they release.

- Package: [package id, e.g. labparcels.iface]
- Version this contract describes: [e.g. 0.1.0]
- Owner: [team or person accountable for these words]
- Status: [draft | active | deprecated]
- Last reviewed: [YYYY-MM-DD]

## 1. Promise

Within the version named above, consumers may rely on:

- the names and shapes listed in section 3 (no silent renames, no silent
  widening or narrowing of a field);
- the identity rules in section 4 (a name keeps meaning what it meant);
- the label standing in section 5 (each public name says which words are
  official and which are translations).

Anything not listed here is internal and may change without notice.

## 2. Versioning

- Versions are selected explicitly by each consumer; nothing upgrades a
  consumer automatically.
- Additive releases (new names only) keep every promise above.
- Any other change ships as a new contract version with a vocabulary
  decision record explaining what moved and why.
- The deprecated standing means: no new consumers, existing consumers get
  [notice period, e.g. two releases] to move.

## 3. Declared words

Entities (things with identity):

| Name | Meaning in one sentence | Standing |
|---|---|---|
| [e.g. Parcel] | [a registered land unit] | [stable | provisional] |
| [e.g. Owner] | [a person or body holding a parcel] | [stable | provisional] |

Relations (how things connect; mark the key fields consumers join on):

| Name | Arguments | Key | Meaning in one sentence |
|---|---|---|---|
| [e.g. owns] | [owner, parcel] | [parcel] | [the owner holds the parcel] |

Enums and constants (closed choices and fixed values):

| Name | Members or value | Meaning in one sentence |
|---|---|---|
| [e.g. ParcelKind] | [residential, commercial, farmland] | [use class of a parcel] |

## 4. Identity rules

- Each declared name keeps one stable identity across releases; spelling
  variants of one member (dotted, bare, qualified) are the same member.
- A rename keeps the old name as a documented alias for [notice period],
  or ships with a recorded decision and a major version step.
- Subtypes never silently change parents; key fields never silently change.

## 5. Labels

- Every public name carries labels saying the language and the standing
  of the wording (official, unofficial, or translation).
- Templates that turn a relation into a sentence name every argument, so
  generated answers read correctly in each supported language.
- Missing wording degrades to plain text; the engine never invents wording.

## 6. What consumers must do

- Import the words; never redeclare them locally under the same meaning.
- Treat the key as a functional dependency: the key fields determine
  the row, so a join outside them is underdetermined. Join on stable
  typed IDs; never on label text or declaration order.
- Record the exact vocabulary version in the consumer lockfile.

## 7. Verification on record

```text
[paste: package test output for the vocabulary package]
```

```text
[paste: producer and reader query outputs showing who declares and who reads each word]
```

## 8. Decision log

| Date | Change | Record |
|---|---|---|
| [YYYY-MM-DD] | [one line, e.g. added ParcelKind.farmland] | [decision record name] |