Skip to content

Naming Conventions ​

This document is the single source of truth for domain vocabulary and identifier naming across Go code, tests, CLI commands, documentation, and commit messages.

AIST does not keep legacy naming aliases for internal backward compatibility — when a name changes, update all callers, tests, and docs directly, and verify with make naming-check.

1. Domain Vocabulary ​

ConceptCanonical NameNotesAvoid
Persisted sessionsession.SessionSession data structureConversation as a type name
Session orchestratorsession.ManagerAppend, compaction, title, pruningsession.Service
Interactive loopinteractive.SessionUser-facing LLM/tool loopAgent, Runner
Single user turnTurnOne real user message + following assistant/tool messagesRound, Question
Persisted messageMessageSession messageEntry for messages
Tool invocationToolCallModel-requested tool callCommand for generic tools
Tool resultToolResultResult written back to sessionOutput for generic tool results
Tool outcomeToolOutcomesuccess / failed / skipped / rejectedResultStatus, ToolStatus
Follow-up callFollowUpModel call triggered by tool resultsAnalysis
Shell commandShellCommandParsed/pending shell commandInvocation as command struct
Query commandCommandTypeQueryRead-only command—
Modify commandCommandTypeModifyState-changing command—
Execution hostTargetLocal or SSH host—
Memory entrymemory.EntryEnvironment knowledge itemmemory.Memory
Memory mutationChangeUnified append / replaceSave for domain model
Account settingsconfig.SettingsRuntime snapshot delivered by serverconfig.Config, remote.ServerConfig
Memory catalog providermemory.CatalogProviderBuilds <memory_catalog> blockmemory.Provider
Prompt setprompt.SetSystem / follow-up / compaction promptsprompt.Provider
Memory snapshot storememory.SnapshotStoreIn-memory loaded snapshotmemory.Store
Logical model clientllm.ServerModelSole client model entry (model="auto")llm.Manager, CloudModel
Terminal rendererRendererTerminal rendering portDisplay as a port/verb

Terminology boundary: user refers strictly to login identity (users, user_id, email); account refers to the configuration + credentials aggregate (AccountProvider, remote.AccountConfig, config.Settings).

2. Go Naming Rules ​

  • General: PascalCase for exported, camelCase for unexported; uppercase initialisms (ID, URL, API, LLM, SSH, JSON, YAML, CLI, HTTP); no underscores in Go identifiers (except test names); never stutter package names (state.Root, config.Settings, memory.Entry, preferences.Data).
  • Constructors: NewX (NewManager, NewStore, NewEditor); bare New is allowed only when a package has a single primary type.
  • Conversions: toX / ToX into a target domain type, fromX out of it.
  • Output Verbs: Render (pure string formatting), Print (write to terminal), Prompt (interactive input), Write / Save (persist to file), Append / Record (append log/event), Apply (apply mutation). Never use Display as a verb.
  • Booleans: Positive, specific names (needsFollowUp, skipConfirm, IsSupportedLanguage); avoid bare handled, asked, stop, state, ok across function boundaries.
  • Errors: Sentinel errors ErrX, error types XError, wrap with fmt.Errorf("...: %w", err).
  • Enums: <Type><Value> (CommandTypeUnknown, CommandTypeQuery, CommandTypeModify); zero value must be safe/explicit (Unknown).
  • Query Methods: Do not use Get prefixes (LookupProvider, EffectiveContextWindow, EffectiveMaxOutputTokens).
  • Struct / Interface Suffixes: Repository, Snapshot, Manager, <Type>Options (app.Options is the sole bare Options where multiple types exist).
  • Package Boundaries: Domain packages (internal/config, internal/session, internal/memory, internal/target) must not depend on UI, CLI, environment variables, or global state; adapters (internal/preferences, internal/token, internal/session/file) depend inward on domain packages.
  • Files & Packages: Lowercase single-word package names (fileedit, commandguard, preferences); snake_case multi-word filenames (account_config.go); kebab-case shell scripts under scripts/.

3. Package-Specific Conventions ​

  • internal/config: Settings holds only server-delivered limits, session, and blacklist (client UI/reply language lives in internal/preferences).
  • internal/llm: ServerModel is the sole client LLM entry; CompletionRequest / CompletionResponse.
  • internal/interactive: Session, Turn, FollowUp, DecisionApprove / DecisionSkip / DecisionRejectRemaining.

4. Prohibited Legacy Identifiers (make naming-check) ​

./scripts/naming-check.sh rejects all deprecated identifiers below:

text
analyzeCommandOutput
needsAnalysis
AnalysisComplete
ContinueAnalysis
processQuestion
RunRestored
RunWithPipe
QueryCommand
ModifyCommand
ResultSuccess
ResultFailed
ResultSkipped
ResultRejected
ToolStatusSuccess
ToolStatusFailed
ToolStatusSkipped
ToolStatusRejected
SaveMode
SaveRequest
SaveResult
SaveAppend
SaveReplace
SaveDelete
Summarizer
SummaryRequest
SummaryResult
session.Service
memory.Service
memory.Provider
config.Provider
prompt.Provider
llm.Manager
CompactBlankLines
DisplayWelcome
DisplayShellCommand
EndRegion
clientConfig
clientLimits
buildClientConfig
remote.ServerConfig
CloudModel
CloudModelOptions
NewCloudModel
cmd/cloud
internal/cloud
deploy/cloud
scripts/build-cloud.sh
release-cloud
aist-cloud
AIST_CLOUD_*

5. Review Checklist ​

  • Does every identifier directly describe behavior and match §1 vocabulary?
  • Are enum zero values safe and boolean names positive/specific?
  • Do output verbs follow Render / Print / Prompt / Save?
  • Did gofmt -l ., go vet ./..., make naming-check, and go test ./... all pass?

Licensed under AGPL-3.0 (Commercial licensing available: contact@aistrun.cc)