Terminology Governance System for Elonn

Problem

We are no longer dealing with isolated naming issues.

Terminology is beginning to leak across:

• services
• runtimes
• APIs
• UI
• documentation
• prompts
• database schemas
• developer assumptions

This creates architectural drift.

Examples already observed:

• "surface" meaning both:

* a discovery/monetization service
* a presentation/navigation/rendering concept
* "messages" being used for:

* direct member communication
* threaded community discussions
* "world" sometimes meaning:

* aggregation layer
* runtime
* "social" sometimes meaning:

* service
* feature category
* "room" encoding the wrong spatial assumptions and later becoming "field"

This is no longer a naming cleanup task.

This is architecture governance.

---

Core Principle

Words are architecture.

In Elonn:

• words define APIs
• words define permissions
• words define mental models
• words define boundaries
• words define data ownership
• words define runtime behavior

If terminology drifts:

• implementation drifts
• developer assumptions drift
• AI-generated code drifts
• service boundaries erode
• product behavior becomes inconsistent

---

Required System

1. Canonical Vocabulary Registry

Create a single authoritative source of truth.

Suggested structure:

/docs/architecture/
    glossary.md
    banned-terms.md
    ontology.md
    domain-map.md

This must become authoritative.

Not guidance.
Not reference material.
Law.

---

2. Canonical Term Format

Every term should follow a strict structure.

Example:

Category:
- Social Primitive

Definition:
- Structured threaded discussion attached to a community, event, object, or context.

Valid Contexts:
- communities
- events
- object discussions

Invalid Contexts:
- direct member communication
- notifications
- ephemeral signaling

Related Terms:
- reply
- thread
- discussion

Forbidden Synonyms:
- message
- chat

Database Implications:
- conversations table
- conversation_replies table

API Implications:
- /conversations/*
```

---

3. Architectural Ontology

You need a formal ontology.

The current confusion exists because terms are crossing layers without explicit ownership.

Suggested Layer Model

Infrastructure Layer
Service Layer
Aggregation Layer
Runtime Layer
Presentation Layer
Interaction Layer
Social Primitive Layer
Spatial Primitive Layer
Economic Layer

Every major concept should belong primarily to one layer.

Example:

| Term | Primary Layer |
| ------------ | ----------------- |
| api | infrastructure |
| auth | infrastructure |
| time | service |
| maps | service |
| social | service |
| world | aggregation |
| web | runtime |
| android | runtime |
| carry | spatial primitive |
| field | spatial primitive |
| conversation | social primitive |
| message | social primitive |
| find | economic |

This immediately exposes overlap and leakage.

---

4. Forbidden Vocabulary System

This is critical.

Most organizations define terms.
Very few explicitly ban terms.

You must ban ambiguous or overloaded language.

Example:

Reason:
- Conflicts with surface.elonn.com
- "surface" already assigned elsewhere
- creates ambiguity between presentation systems and economic discovery systems

Use Instead:
- presentation engine
- runtime compositor
- panel system
- spatial compositor
```

Another:

Forbidden In:
- communities
- events
- threaded discussions

Reason:
- reserved exclusively for direct member-to-member communication

Use Instead:
- conversation
- reply
- discussion
```

This prevents semantic regression.

---

5. Terminology Enforcement

This cannot remain manual.

Documentation Enforcement

All architecture documents should:

• use canonical terms only
• reject forbidden terminology
• reference glossary definitions

---

AI Prompt Enforcement

All Codex/Claude instructions should begin with something similar to:

Do not invent synonyms.

See:
- /docs/architecture/glossary.md
- /docs/architecture/banned-terms.md
- /docs/architecture/ontology.md
```

Otherwise AI systems will continuously reintroduce entropy.

---

Repository Auditing

Audit the codebase directly.

Examples:

grep -R "message" .
grep -R "surface engine" .
grep -R "room layer" .

Then create remediation lists.

Eventually:

/scripts/terminology_audit.sh

or CI-based validation.

---

Database Audit

Database terminology mistakes are extremely expensive later.

Audit:

• table names
• column names
• enum values
• migration names
• API routes

before growth accelerates.

---

Recommended Immediate Process

Phase 1 - Freeze Vocabulary Expansion

Before additional implementation:

Create:

/docs/architecture/
    glossary.md
    banned-terms.md
    ontology.md

Do not continue expanding terminology organically.

---

Phase 2 - Full Terminology Inventory

Inventory:

• services
• runtimes
• social primitives
• spatial primitives
• UI concepts
• rendering concepts
• economic systems
• navigation systems
• moderation systems
• relationship systems

Identify:

• duplicates
• overloaded terms
• conflicting metaphors
• layer leakage
• runtime leakage
• service ambiguity

---

Phase 3 - Assign Ownership

Every major term gets:

• definition
• owning layer
• allowed contexts
• forbidden contexts
• related terms
• deprecated synonyms

---

Phase 4 - Refactor Aggressively Now

Rename early.

Later:

• APIs calcify
• prompts calcify
• database schemas calcify
• public docs calcify
• developer habits calcify

Right now the cost is manageable.

Later it becomes institutional debt.

---

Most Important Insight

Elonn is not just a software platform.

It is a semantic environment spanning:

• services
• runtimes
• spatial systems
• social systems
• economic systems
• AI-assisted development systems

That means terminology precision is not documentation polish.

It is infrastructure.