authorgravatar for jason.laster.11@gmail.comJason Laster <jason.laster.11@gmail.com> 2026-03-08 22:40:44-06:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-03-08 21:40:44-07:00
log5bc79807ec33f0b7f3633ad6dc54fcedf0de3a73
tree1cefeadec0b6d7e73f86a5a8b306e00c3fef47e7
parent8fe21d7583a21a19c98b0e24a64dd0d7029b41b0
signature Signed by PGP key B5690EEEBB952194

Add an encyclopedia of common terms (#613)

1 files changed, 180 insertions(+), 0 deletions(-)

.docs/encyclopedia.md created+180
......@@ -0,0 +1,180 @@
1# Encyclopedia
2
3This is a living glossary for T3 Code. It explains what common terms mean in this codebase.
4
5## Table of contents
6
7- [Project and workspace](#project-and-workspace)
8- [Thread timeline](#thread-timeline)
9- [Orchestration](#orchestration)
10- [Provider runtime](#provider-runtime)
11- [Checkpointing](#checkpointing)
12
13## Concepts
14
15### Project and workspace
16
17#### Project
18
19The top-level workspace record in the app. In [the orchestration contracts][1], a project has a `workspaceRoot`, a title, and one or more threads. See [workspace-layout.md][2].
20
21#### Workspace root
22
23The root filesystem path for a project. In [the orchestration model][1], it is the base directory for branches and optional worktrees. See [workspace-layout.md][2].
24
25#### Worktree
26
27A Git worktree used as an isolated workspace for a thread. If a thread has a `worktreePath` in [the contracts][1], it runs there instead of in the main working tree. Git operations live in [GitCore.ts][3].
28
29### Thread timeline
30
31#### Thread
32
33The main durable unit of conversation and workspace history. In [the orchestration contracts][1], a thread holds messages, activities, checkpoints, and session-related state. See [projector.ts][4].
34
35#### Turn
36
37A 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][1], [ProviderRuntimeIngestion.ts][5], and [CheckpointReactor.ts][6].
38
39#### Activity
40
41A user-visible log item attached to a thread. In [the contracts][1], activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in [projector.ts][4].
42
43### Orchestration
44
45Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is [OrchestrationEngine.ts][7], with core logic in [decider.ts][8] and [projector.ts][4].
46
47#### Aggregate
48
49The domain object a command or event belongs to. In [the contracts][1], that is usually `project` or `thread`. See [decider.ts][8].
50
51#### Command
52
53A typed request to change domain state. In [the contracts][1], commands are validated in [commandInvariants.ts][9] and turned into events by [decider.ts][8].
54Examples include `thread.create`, `thread.turn.start`, and `thread.checkpoint.revert`.
55
56#### Domain Event
57
58A persisted fact that something already happened. In [the contracts][1], events are the source of truth, and [projector.ts][4] shows how they are applied.
59Examples include `thread.created`, `thread.message-sent`, and `thread.turn-diff-completed`.
60
61#### Decider
62
63The pure orchestration logic that turns commands plus current state into events. The core implementation is in [decider.ts][8], with preconditions in [commandInvariants.ts][9].
64
65#### Projection
66
67A read-optimized view derived from events. See [projector.ts][4], [ProjectionPipeline.ts][11], and [ProjectionSnapshotQuery.ts][10].
68
69#### Projector
70
71The logic that applies domain events to the read model or projection tables. See [projector.ts][4] and [ProjectionPipeline.ts][11].
72
73#### Read model
74
75The current materialized view of orchestration state. In [the contracts][1], it holds projects, threads, messages, activities, checkpoints, and session state. See [ProjectionSnapshotQuery.ts][10] and [OrchestrationEngine.ts][7].
76
77#### Reactor
78
79A side-effecting service that handles follow-up work after events or runtime signals. Examples include [CheckpointReactor.ts][6], [ProviderCommandReactor.ts][12], and [ProviderRuntimeIngestion.ts][5].
80
81#### Receipt
82
83A lightweight typed runtime signal emitted when an async milestone completes. See [RuntimeReceiptBus.ts][13].
84Examples include `checkpoint.baseline.captured`, `checkpoint.diff.finalized`, and `turn.processing.quiesced`, which are emitted by flows such as [CheckpointReactor.ts][6].
85
86#### Quiesced
87
88"Quiesced" means a turn has gone quiet and stable. In [the receipt schema][13], it means the follow-up work has settled, including work in [CheckpointReactor.ts][6].
89
90### Provider runtime
91
92The live backend agent implementation and its event stream. The main service is [ProviderService.ts][14], the adapter contract is [ProviderAdapter.ts][15], and the overview is in [provider-architecture.md][16].
93
94#### Provider
95
96The backend agent runtime that actually performs work. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17].
97
98#### Session
99
100The live provider-backed runtime attached to a thread. Session shape is in [the orchestration contracts][1], and lifecycle is managed in [ProviderService.ts][14].
101
102#### Runtime mode
103
104The safety/access mode for a thread or session. In [the contracts][1], the main values are `approval-required` and `full-access`. See [runtime-modes.md][18].
105
106#### Interaction mode
107
108The agent interaction style for a thread. In [the contracts][1], the main values are `default` and `plan`. See [runtime-modes.md][18].
109
110#### Assistant delivery mode
111
112Controls how assistant text reaches the thread timeline. In [the contracts][1], `streaming` updates incrementally and `buffered` delivers a completed result. See [ProviderService.ts][14].
113
114#### Snapshot
115
116A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See [ProjectionSnapshotQuery.ts][10], [ProviderAdapter.ts][15], and [CheckpointStore.ts][19].
117
118### Checkpointing
119
120Checkpointing captures workspace state over time so the app can diff turns and restore earlier points. The main pieces are [CheckpointStore.ts][19], [CheckpointDiffQuery.ts][20], and [CheckpointReactor.ts][6].
121
122#### Checkpoint
123
124A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in [CheckpointStore.ts][19] plus a projected summary from [ProjectionCheckpoints.ts][21]. Capture and lifecycle work happen in [CheckpointReactor.ts][6].
125
126#### Checkpoint ref
127
128The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in [the contracts][1], constructed in [Utils.ts][22], and used by [CheckpointStore.ts][19].
129
130#### Checkpoint baseline
131
132The starting checkpoint for diffing a thread timeline. This flow is surfaced through [RuntimeReceiptBus.ts][13], coordinated in [CheckpointReactor.ts][6], and supported by [Utils.ts][22].
133
134#### Checkpoint diff
135
136The patch difference between two checkpoints. Query logic lives in [CheckpointDiffQuery.ts][20], diff parsing lives in [Diffs.ts][23], and finalization is coordinated by [CheckpointReactor.ts][6].
137
138#### Turn diff
139
140The file patch and changed-file summary for one turn. It is usually computed in [CheckpointDiffQuery.ts][20], represented in [the contracts][1], and recorded into thread state by [projector.ts][4].
141
142## Practical Shortcuts
143
144- If you see `requested`, think "intent recorded".
145- If you see `completed`, think "result applied".
146- If you see `receipt`, think "async milestone signal".
147- If you see `checkpoint`, think "workspace snapshot for diff/restore".
148- If you see `quiesced`, think "all relevant follow-up work has gone idle".
149
150## Related Docs
151
152- [architecture.md][24]
153- [provider-architecture.md][16]
154- [runtime-modes.md][18]
155- [workspace-layout.md][2]
156
157[1]: ../packages/contracts/src/orchestration.ts
158[2]: ./workspace-layout.md
159[3]: ../apps/server/src/git/Layers/GitCore.ts
160[4]: ../apps/server/src/orchestration/projector.ts
161[5]: ../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
162[6]: ../apps/server/src/orchestration/Layers/CheckpointReactor.ts
163[7]: ../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
164[8]: ../apps/server/src/orchestration/decider.ts
165[9]: ../apps/server/src/orchestration/commandInvariants.ts
166[10]: ../apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
167[11]: ../apps/server/src/orchestration/Layers/ProjectionPipeline.ts
168[12]: ../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
169[13]: ../apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
170[14]: ../apps/server/src/provider/Layers/ProviderService.ts
171[15]: ../apps/server/src/provider/Services/ProviderAdapter.ts
172[16]: ./provider-architecture.md
173[17]: ../apps/server/src/provider/Layers/CodexAdapter.ts
174[18]: ./runtime-modes.md
175[19]: ../apps/server/src/checkpointing/Services/CheckpointStore.ts
176[20]: ../apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts
177[21]: ../apps/server/src/persistence/Services/ProjectionCheckpoints.ts
178[22]: ../apps/server/src/checkpointing/Utils.ts
179[23]: ../apps/server/src/checkpointing/Diffs.ts
180[24]: ./architecture.md