Skip to content

Instantly share code, notes, and snippets.

@savarin

savarin/00-terminology.md

Last active June 27, 2026 16:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save savarin/b8294b7269866223f320abf159eaa4e2 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save savarin/b8294b7269866223f320abf159eaa4e2 to your computer and use it in GitHub Desktop.
Download ZIP
The Rewrite: Python Edition — Terminology Register — Pass 2
Raw
00-terminology.md

← Back to Index

Terminology Register — Pass 2

Canonical forms established during copy-edit Pass 2 of Chapters 1–5. All subsequent chapters should match these.

Note: Code identifiers use Python conventions (snake_case for functions/variables, PascalCase for classes/protocols). The underlying source codebase is TypeScript; these are the Python-edition canonical forms.

Code Identifiers (always in backtick code font)

Term Canonical form Notes
drive_run drive_run snake_case function
RunAgent RunAgent PascalCase class
RunLoop RunLoop PascalCase protocol
DriveRunOptions DriveRunOptions PascalCase dataclass
AgentProfile AgentProfile PascalCase dataclass
AgentContext AgentContext PascalCase dataclass
AgentSubmission AgentSubmission PascalCase dataclass
AgentTurnJournal AgentTurnJournal PascalCase union type alias
AgentExecutionStore AgentExecutionStore PascalCase protocol
SessionFactory SessionFactory PascalCase class; "session factory" (lowercase) only when describing the general pattern, not the v2 class
SessionStore SessionStore PascalCase; the v2-narrowed transcript-only store
SandboxApi SandboxApi PascalCase protocol; never "sandbox API" or "Sandbox API" in prose referring to the protocol
RunSink RunSink PascalCase protocol
Chat Chat PascalCase protocol
ModelProvider ModelProvider PascalCase protocol
ApprovalGate ApprovalGate PascalCase protocol
PersonDirectory PersonDirectory PascalCase protocol
Coordinator Coordinator PascalCase class; capitalize in prose when referring to the v2 component
ToolRegistry ToolRegistry PascalCase class
WorkflowRegistry WorkflowRegistry PascalCase class

Prose Terms (no code font)

Term Canonical form Notes
v1 / v2 v1, v2 Always lowercase; never V1, V2
turn turn Lowercase in all prose contexts
session session (prose) / Session (the class) Lowercase in prose; code font when referring to the Python class
pi agent pi Lowercase "pi"; refers to the external pi-agent-core library
drive-to-idle drive-to-idle Hyphenated when used as a compound modifier; "drive to idle" as a verb phrase
construction root construction root Lowercase; "the construction root" in prose
composition root composition root Lowercase; synonym for construction root (v1 usage)
seam seam Lowercase

Versioning

  • Use v1 for the Fly VM-based runtime (apps/runtime-v1).
  • Use v2 for the pool-based harness (apps/runtime).
  • Never prefix with a capital letter (not V1, not V2).

Section Header Style

Chapters 1–5 use title case for all section headers. After a colon in a header, capitalize the first word. Examples established in this pass:

  • "## The Dropped Seams: Scope, Not Mistakes" (Ch. 3)
  • "## v1's Envelope: The Await" (Ch. 5)
  • "## The Coordinator: The Turn as a State Machine" (Ch. 5)
  • "## v1: A Runtime That Owns Its Sessions" (Ch. 4)

Exception: code identifiers retain their canonical casing even in headers (e.g., "## The Inner Loop: drive_run").

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment