Encyclopedia

June 20, 2026 ยท View on GitHub

This is a living glossary for T3 Code. It explains what common terms mean in this codebase.

Table of contents

Concepts

Project and workspace

Project

The top-level workspace record in the app. In the orchestration contracts, a project has a workspaceRoot, a title, and one or more threads. See workspace-layout.md.

Workspace root

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.

Worktree

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 in GitCore.ts.

Thread timeline

Thread

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.

Turn

A single user-to-assistant work cycle inside a thread. It starts with user input and ends when follow-up work like checkpointing settles. See the contracts, ProviderRuntimeIngestion.ts, and CheckpointReactor.ts.

Activity

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

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.

Aggregate

The domain object a command or event belongs to. In the contracts, that is usually project or thread. See decider.ts.

Command

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.

Domain Event

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.

Decider

The pure orchestration logic that turns commands plus current state into events. The core implementation is in decider.ts, with preconditions in commandInvariants.ts.

Projection

A read-optimized view derived from events. See projector.ts, ProjectionPipeline.ts, and ProjectionSnapshotQuery.ts.

Projector

The logic that applies domain events to the read model or projection tables. See projector.ts and ProjectionPipeline.ts.

Read model

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.

Reactor

A side-effecting service that handles follow-up work after events or runtime signals. Examples include CheckpointReactor.ts, ProviderCommandReactor.ts, and ProviderRuntimeIngestion.ts.

Receipt

A lightweight typed runtime signal emitted when an async milestone completes. See RuntimeReceiptBus.ts. Examples include checkpoint.baseline.captured, checkpoint.diff.finalized, and turn.processing.quiesced, which are emitted by flows such as CheckpointReactor.ts.

Quiesced

"Quiesced" means a turn has gone quiet and stable. In the receipt schema, it means the follow-up work has settled, including work in CheckpointReactor.ts.

Provider runtime

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 provider-architecture.md.

Provider

The backend agent runtime that actually performs work. See ProviderService.ts, ProviderAdapter.ts, and CodexAdapter.ts.

Session

The live provider-backed runtime attached to a thread. Session shape is in the orchestration contracts, and lifecycle is managed in ProviderService.ts.

Runtime mode

The safety/access mode for a thread or session. In the contracts, the main values are approval-required and full-access. See runtime-modes.md.

Interaction mode

The agent interaction style for a thread. In the contracts, the main values are default and plan. See runtime-modes.md.

Assistant delivery mode

Controls how assistant text reaches the thread timeline. In the contracts, streaming updates incrementally and buffered delivers a completed result. See ProviderService.ts.

Snapshot

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

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.

Checkpoint

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.

Checkpoint ref

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.

Checkpoint baseline

The starting checkpoint for diffing a thread timeline. This flow is surfaced through RuntimeReceiptBus.ts, coordinated in CheckpointReactor.ts, and supported by Utils.ts.

Checkpoint diff

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.

Turn diff

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.

Practical Shortcuts

  • If you see requested, think "intent recorded".
  • If you see completed, think "result applied".
  • If you see receipt, think "async milestone signal".
  • If you see checkpoint, think "workspace snapshot for diff/restore".
  • If you see quiesced, think "all relevant follow-up work has gone idle".