Semantic Suffixing Naming System

This page documents the current naming direction for the architecture: semantic suffixing.

The goal is simple. A class name should explain its architectural role without opening the file.

Why this exists

Historically, the word Substrate was used both for reusable inheritance layers and for fully assembled runtime classes. That created ambiguity when reading code and design docs.

Semantic suffixing resolves that ambiguity by assigning one role per suffix.

Core vocabulary

Suffix or term	Meaning	Example
Lamina	An inherited structural layer. Incomplete on its own.	BaseLamina, AgenticLamina
Substrate	A fully assembled concrete runtime class.	CliSensoryCortexSubstrate
Cortex	Domain region marker included in names for cortex-specialized units.	SensoryCortexLamina, PrefrontalCortexSubstrate
Synthesizer	A factory that responds to broadcast signals by producing modulators.	CortexLaminaSynthesizer
Signal	A message that asks the system for a specific action or modulator.	Signal
Reply	A return message that carries the outcome of a signal.	Reply
Broadcast	A diffuse message delivered to multiple recipients.	Broadcast
Neuromodulators	The mediation boundary and runtime registry that receives signals from RAS, fans out to synthesizers, and exposes artifact references.	Neuromodulators
Modulator	A dynamic runtime influence injected at launch time or runtime.	DopamineModulator
Cocktail	A grouped runtime state configuration collected from one or more modulators.	ModulatorCocktail

Role split

Use this distinction everywhere in docs and naming discussions:

1. Laminae define structure and capability layers.
2. Substrates are usable runtime objects.
3. RAS sends modulation signals to Neuromodulators.
4. Synthesizers produce modulators in response to Neuromodulators broadcast fanout and publish them to Neuromodulators.
5. RAS resolves published modulators from Neuromodulators by artifact reference.
6. Modulators define runtime state.
7. Signals and reply objects capture orchestration flow explicitly.

In one sentence:

“A substrate is composed from laminae and configured by a modulator cocktail assembled through RAS signals to Neuromodulators and synthesizer-produced reply objects.”

Naming rules

If this model is adopted consistently in code, use the following rules:

1. Every abstract inheritance layer ends in Lamina.
2. Every concrete assembled runtime class ends in Substrate.
3. Region terms stay explicit in the middle of the name when relevant, such as Cortex, Thalamus, or Cerebellum.
4. Factory classes that produce modulators end in Synthesizer.
5. Messaging types use Signal, Reply, or Broadcast when they represent relay traffic.
6. Behavioral state names use Modulator or Cocktail.

Examples:

1. BaseLamina
2. AgenticLamina
3. CortexLamina
4. SensoryMotorCortexLamina
5. SensoryCortexLamina
6. CliSensoryCortexSubstrate
7. PrefrontalCortexSubstrate
8. CortexLaminaSynthesizer
9. Signal
10. Reply
11. Broadcast

Why this improves readability

Semantic suffixing creates immediate role clarity:

1. You can distinguish scaffolding from runnable units by name alone.
2. You avoid collisions where two classes have the same stem but different architectural purpose.
3. IDE autocomplete groups related classes predictably.

Cost and mitigation

The tradeoff is verbosity. Names can become long.

Recommended mitigation:

1. Use multiline class declarations and function signatures.
2. Use IDE rename tools for refactors.
3. Use local aliases sparingly only where readability clearly improves.

Adoption guidance

This convention is most effective when used consistently.

Partial adoption can increase confusion, so decide explicitly whether the project is:

1. Documentation-only for now.
2. Migrating selected packages.
3. Performing full vocabulary migration.

If migration is chosen, record the decision in an ADR before broad renames.