openyield/docs/shared/lexicon.md

# Lexicon

OpenYield bans 10 financial terms as standalone words (REQ-012). The firewall
scans every Go file under `x/` and every Markdown file under `README.md` +
`docs/`, and fails the build on any standalone occurrence. This page documents
**why** the terms are banned and **what to say instead** — the replacements,
not the banned literals.

## Why a lexicon

The words a legacy financial institution uses carry the shapes of that
institution: custodial positions, jurisdiction-bound units, and
speculation-language. OpenYield is a jurisdiction-light, public-good mesh for
real production; using the old words would import the old shapes. The
lexicon firewall keeps the mesh's language aligned with its covenant. The
firewall is enforced in code by two sibling Go tests
(`lexicon_meta_test.go` for `x/**/*.go`;
`lexicon_meta_docs/lexicon_meta_docs_test.go` for `README.md` +
`docs/**/*.md`), both using `lexicon.FindBannedTerm` (word-boundary,
case-insensitive). Word-boundary matching means "OpenYield" is safe — the
firewall bans standalone words, not substrings.

## The 10 banned terms and their safe replacements

The firewall bans 10 standalone words. This page does not write the banned
words as literals (the firewall scans this page); it describes them by the
concept each belongs to, and gives the safe replacement.

### 1. The custodial-position word

A legacy institution holds your value in a custodial position. OpenYield
does not: a Holder owns their **Stash**, a Stand owns its **Vault**, the mesh
owns the **Root-Pool**. The Holder's identity is a **Reach**, and the Holder
themselves is a **Holder** — never the banned custodial-position word.

- Banned: the word for a custodial position.
- Safe: **Holder**, **Reach**, **Stash**, **Vault**, **Root-Pool**.

### 2. The legacy-institution word

The legacy financial institution itself is banned as a concept. OpenYield is
a **mesh**, a **public good**, a **protocol** — not that word.

- Banned: the word for a legacy financial institution.
- Safe: **mesh**, **protocol**, **public good**.

### 3. The place-value word

The word for a place to hold value under custody is banned. Use the
**Stash** (Holder-level), the **Vault** (Stand-level), or the **Root-Pool**
(treasury).

- Banned: the word for a place value is held.
- Safe: **Stash**, **Vault**, **Root-Pool**, **Storage Pools**.

### 4. The put-in word

The verb for putting value into a custodial position is banned. Use **hold**,
**store**, **move**, or **transfer**.

- Banned: the verb for placing value under custody.
- Safe: **hold**, **store**, **move**, **transfer**, **Pass-Act**.

### 5. The passive-value word

The word for value earned passively on a custodial position is banned. For
bonds, use **coupon**. For the mesh's metric, use **real production** or
**real return**.

- Banned: the word for passive value on a custodial position.
- Safe: **coupon**, **real production**, **real return**.

### 6. The standalone metric word

The standalone word for a return metric is banned (it is the same concept as
#5 in verb form). Use **real production**, **real return**, or **coupon**
(for bonds). "OpenYield" is safe — word-boundary matching does not flag the
banned term inside an identifier.

- Banned: the standalone return-metric word.
- Safe: **real production**, **real return**, **coupon**. **OpenYield** is safe.

### 7. The medium-of-exchange word

The word for a national medium of exchange is banned. The mesh's unit is
**Bread** (see [Bread scale](bread-scale.md)). For a foreign-exchange pair,
use **Forex** (allowed) with **base-asset** / **quote-asset** labels, or
**Bread / Asset**.

- Banned: the word for a national medium of exchange.
- Safe: **Bread**, **asset**, **Forex**, **base-asset**, **quote-asset**.

### 8. The first national-unit word

The word for the first major national unit is banned. Use **Bread** or
opaque chain names (e.g., "Polygon", "OY-Chain").

- Banned: the first national-unit word.
- Safe: **Bread**, **asset**, chain names.

### 9. The second national-unit word

The word for the second major national unit is banned (the firewall bans it
as a standalone word; "european" is safe by word-boundary). Use **Bread** or
opaque chain names.

- Banned: the second national-unit word.
- Safe: **Bread**, **asset**, chain names. **European** is safe (word-boundary).

### 10. The set-aside word

The word for value set aside under custody is banned. Use **Stash**,
**Vault**, or **Root-Pool**.

- Banned: the word for value set aside.
- Safe: **Stash**, **Vault**, **Root-Pool**.

### 11. The holder-of-value word

The word for the person who holds value under custody at a legacy
institution is banned. Use **Holder**, **Freeholder**, or **Nomad**.

- Banned: the word for a custodial-position holder.
- Safe: **Holder**, **Freeholder**, **Nomad**, **Reach**.

> **Note**: the firewall bans 10 standalone words; this page lists 11
> replacements because two of the banned words (the passive-value word and
> the standalone metric word) share a concept and get the same replacement
> family (**coupon** / **real production** / **real return**).

## How the firewall works

The firewall uses `lexicon.FindBannedTerm` — a word-boundary, case-insensitive
regex match — so:

- "OpenYield" is **safe**: the standalone banned term inside an identifier
  does not match (word-boundary).
- "european" is **safe**: the standalone national-unit word inside a larger
  word does not match.
- The standalone banned word in prose **is** matched and fails the build.

The firewall's own source (`lexicon/lexicon.go`) assembles the banned terms
at runtime from two-character fragments, so the firewall's own code does not
contain any banned term as a literal substring. The two sibling meta-tests
(`lexicon_meta_test.go` and `lexicon_meta_docs/lexicon_meta_docs_test.go`)
each include a self-test table that verifies detection of all 10 banned
terms from the single source `lexicon.BannedTerms()` (G-014 drift
prevention).