cloudinit-bot
a780884379
P1 complete. Docs lexicon firewall (lexicon_meta_docs_test.go, 5 tests incl. G-013 walk-coverage + G-014 shared self-test). MkDocs Material scaffold with 26-page nav (G-011). README.md + docs/index.md + 7 docs/shared/ pages. Both firewalls green, go test ./... 22 packages green, no regression. ---ci--- project: oy phase: 1 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [REQ-028] partial: [REQ-027] ---/ci---
5.9 KiB
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). 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).