For maintainers. Using T3 Code? See docs/user.
This is a living glossary for T3 Code. It explains what common terms mean in this codebase.
The top-level workspace record in the app. In the orchestration contracts, a project has a workspaceRoot and a title. It does not contain threads: OrchestrationProject and OrchestrationThread are separate arrays on the read model, and a project can have zero threads. See workspace-layout.md.
The root filesystem path for a project. In the orchestration model, it is the base directory for branches and optional worktrees. See workspace-layout.md.
A Git worktree used as an isolated workspace for a thread. If a thread has a worktreePath in the contracts, it runs there instead of in the main working tree. Git operations live behind the VCS driver contract in apps/server/src/vcs/VcsDriver.ts, implemented by GitVcsDriverCore.ts.
The main durable unit of conversation and workspace history. In the orchestration contracts, a thread holds messages, activities, checkpoints, and session-related state. See projector.ts.
A single user-to-assistant work cycle inside a thread. It starts with user input and ends when the session leaves running status, which projector.ts treats as the authoritative completion signal (settledTurnStateForSessionStatus). Checkpoint and diff work may settle afterward without changing when the turn ended. See the contracts and ProviderRuntimeIngestion.ts.
A user-visible log item attached to a thread. In the contracts, activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in projector.ts.
Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is OrchestrationEngine.ts, with core logic in decider.ts and projector.ts.
The domain object a command or event belongs to. In the contracts, that is usually project or thread. See decider.ts.
A typed request to change domain state. In the contracts, commands are validated in commandInvariants.ts and turned into events by decider.ts.
Examples include thread.create, thread.turn.start, and thread.checkpoint.revert.
A persisted fact that something already happened. In the contracts, events are the source of truth, and projector.ts shows how they are applied.
Examples include thread.created, thread.message-sent, and thread.turn-diff-completed.
The pure orchestration logic that turns commands plus current state into events. The core implementation is in decider.ts, with preconditions in commandInvariants.ts.
A read-optimized view derived from events. See projector.ts, ProjectionPipeline.ts, and ProjectionSnapshotQuery.ts.
The logic that applies domain events to the read model or projection tables. See projector.ts and ProjectionPipeline.ts.
The current materialized view of orchestration state. In the contracts, it holds projects, threads, messages, activities, checkpoints, and session state. See ProjectionSnapshotQuery.ts and OrchestrationEngine.ts.
A side-effecting service that handles follow-up work after events or runtime signals. Examples include CheckpointReactor.ts, ProviderCommandReactor.ts, and ProviderRuntimeIngestion.ts.
A typed signal emitted when an async milestone completes, such as checkpoint.baseline.captured, checkpoint.diff.finalized, or turn.processing.quiesced. Receipts are a test-only mechanism: the production RuntimeReceiptBusLive publish is a no-op and only the test layer is PubSub-backed. Do not build production behavior on them. See RuntimeReceiptBus.ts and CheckpointReactor.ts.
"Quiesced" means a turn has gone quiet and stable: follow-up work such as CheckpointReactor.ts has settled. It appears in the receipt schema, so in practice it is something tests wait on rather than a production signal.
The live backend agent implementation and its event stream. The main service is ProviderService.ts, the adapter contract is ProviderAdapter.ts, and the overview is in providers.md.
The backend agent runtime that actually performs work. Five drivers ship built in: Codex, Claude, Cursor, Grok, and OpenCode. See ProviderService.ts, ProviderAdapter.ts, and CodexAdapter.ts as a representative adapter.
The live provider-backed runtime attached to a thread. Session shape is in the orchestration contracts, and lifecycle is managed in ProviderService.ts.
The safety/access mode for a thread or session. The contracts define four values: approval-required, auto-accept-edits, auto, and full-access. See permission modes.
The agent interaction style for a thread. In the contracts, the values are default and plan.
Controls how assistant text reaches the thread timeline. In the contracts, streaming updates incrementally and buffered accumulates text. Buffered delivery is not held until the turn completes: it spills once accumulated text would exceed 24,000 characters, and flushes at approval and user-input boundaries. See ProviderRuntimeIngestion.ts.
A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See ProjectionSnapshotQuery.ts, ProviderAdapter.ts, and CheckpointStore.ts.
Checkpointing captures workspace state over time so the app can diff turns and restore earlier points. The main pieces are CheckpointStore.ts, CheckpointDiffQuery.ts, and CheckpointReactor.ts.
A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in CheckpointStore.ts plus a projected summary from ProjectionCheckpoints.ts. Capture and lifecycle work happen in CheckpointReactor.ts.
The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in the contracts, constructed in Utils.ts, and used by CheckpointStore.ts.
The starting checkpoint for diffing a thread timeline. This flow is surfaced through RuntimeReceiptBus.ts, coordinated in CheckpointReactor.ts, and supported by Utils.ts.
The patch difference between two checkpoints. Query logic lives in CheckpointDiffQuery.ts, diff parsing lives in Diffs.ts, and finalization is coordinated by CheckpointReactor.ts.
The file patch and changed-file summary for one turn. It is usually computed in CheckpointDiffQuery.ts, represented in the contracts, and recorded into thread state by projector.ts.
- If you see
requested, think "intent recorded". - If you see
completed, think "result applied". - If you see
receipt, think "async milestone signal, for tests". - If you see
checkpoint, think "workspace snapshot for diff/restore". - If you see
quiesced, think "all relevant follow-up work has gone idle".