One request, every boundary
Step through a user turn from a client command to an ordered SQL commit, provider-native execution, canonical event ingestion, checkpoint diff, and streamed UI state.
What this chapter resolves
- Build a causal mental model before studying individual modules.
- Distinguish the synchronous command acknowledgement from asynchronous provider work.
- Locate durability, side effects, streaming, and checkpoint settlement.
The easiest way to understand T3 Code is to separate accepting intent from performing work. This first trace deliberately follows a turn on an existing thread with no new attachments or worktree bootstrap. That keeps one transactional write path visible; the multi-step bootstrap branch appears immediately afterwards.
End-to-end request trace
Move through the ordered stages or play the trace once.
Step 1 of 11: Compose
The client builds a typed command
The local, hosted, or Electron web renderer—or mobile—creates a thread.turn.start command for an existing thread.
packages/contracts/src/orchestration.ts:847–864 ↗- Compose · The client builds a typed command
The local, hosted, or Electron web renderer—or mobile—creates a thread.turn.start command for an existing thread.
packages/contracts/src/orchestration.ts:847–864↗ - Authorize · The WebSocket method checks scope
The connection is authenticated, but each RPC method still has its own required OAuth scope. The socket is a transport, not blanket authority.
apps/server/src/auth/RpcAuthorization.ts:18–139↗ - Normalize · The server canonicalizes external input
Before dispatch, the RPC path normalizes timestamps, workspace roots, and attachments. Attachment bytes—when present—are written before the orchestration transaction.
apps/server/src/orchestration/Normalizer.ts:46–178↗ - Queue · Dispatch enters one ordered queue
OrchestrationEngine offers a CommandEnvelope to one queue. A single worker processes envelopes, which makes command decisions totally ordered.
apps/server/src/orchestration/Layers/OrchestrationEngine.ts:331–368↗ - Decide · The I/O-free decision layer plans facts
Before the SQL transaction, the decider checks invariants and returns one or more events. It performs no persistence, filesystem, or provider I/O, but it does read the clock and create UUIDs through Effect dependencies.
apps/server/src/orchestration/decider.ts:18–173↗ - Commit · Event, projection, and receipt commit together
Inside one SQL transaction the engine appends events, updates durable projections, and records the accepted idempotency receipt.
apps/server/src/orchestration/Layers/OrchestrationEngine.ts:197–259↗ - React · A reactor performs the provider side effect
ProviderCommandReactor observes committed turn intent, resolves the provider instance, starts or resumes a session, and sends the turn.
apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1060–1174↗ - Adapt · The harness speaks its native protocol
Codex app-server, Claude Agent SDK, ACP, or OpenCode produces native notifications. Its adapter maps them into the canonical runtime union.
packages/contracts/src/providerRuntime.ts:1139–1193↗ - Ingest · Runtime facts become internal commands
ProviderRuntimeIngestion turns content, activities, approvals, plans, usage, and lifecycle facts back into orchestration commands.
apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts:1490–1874↗ - Sync · Committed state reaches clients
An initial HTTP snapshot establishes authoritative state; the WebSocket subscription resumes after its sequence cursor and carries committed thread events.
packages/client-runtime/src/state/threads.ts:534–645↗ - Checkpoint · An eligible Git workspace is captured in parallel
CheckpointReactor independently sees turn.completed, attempts hidden-ref capture, then dispatches thread.turn.diff.complete. Only the engine persists that result.
apps/server/src/orchestration/Layers/CheckpointReactor.ts:270–316↗
The command is deliberately rich
const ClientThreadTurnStartCommand = Schema.Struct({
type: Schema.Literal("thread.turn.start"),
commandId: CommandId,
threadId: ThreadId,
message: Schema.Struct({
messageId: MessageId,
role: Schema.Literal("user"),
text: Schema.String,
attachments: Schema.Array(UploadChatAttachment),
}),
modelSelection: Schema.optional(ModelSelection),
titleSeed: Schema.optional(TrimmedNonEmptyString),
runtimeMode: RuntimeMode,
interactionMode: ProviderInteractionMode,
bootstrap: Schema.optional(ThreadTurnStartBootstrap),
sourceProposedPlan: Schema.optional(SourceProposedPlanReference),
createdAt: IsoDateTime,
});The acknowledgement is not the answer
yield* projectionPipeline.bootstrap;
commandReadModel = yield* projectionSnapshotQuery.getCommandReadModel();
const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));
yield* Effect.forkScoped(worker);
yield* Effect.logDebug("orchestration engine started").pipe(
Effect.annotateLogs({ sequence: commandReadModel.snapshotSequence }),
);
const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive, limit) =>
eventStore.readFromSequence(fromSequenceExclusive, limit);
const dispatch: OrchestrationEngineShape["dispatch"] = (command, options) =>
Effect.gen(function* () {
const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();
yield* Queue.offer(commandQueue, {
command,
origin: options?.origin,
result,
startedAtMs: yield* Clock.currentTimeMillis,
});
return yield* Deferred.await(result);
});
return {
readEvents,
dispatch,
// Each access creates a fresh PubSub subscription so that multiple
// consumers (wsServer, ProviderRuntimeIngestion, CheckpointReactor, etc.)
// each independently receive all domain events.
get streamDomainEvents(): OrchestrationEngineShape["streamDomainEvents"] {
return Stream.fromPubSub(eventPubSub);
},
// The command read model's snapshotSequence tracks the latest committed
// event sequence (updated on the worker fiber). A plain property read is a
// consistent, committed value — reassignment of `commandReadModel` is
// atomic on the single-threaded event loop.
latestSequence: Effect.sync(() => commandReadModel.snapshotSequence),export const DispatchResult = Schema.Struct({
sequence: NonNegativeInt,
});
export type DispatchResult = typeof DispatchResult.Type;The turn reaches another milestone when its projected provider session is no longer
running. Checkpoint state can arrive independently, and capture may be missing,
skipped, or erroneous. A single “complete” boolean cannot faithfully represent all
three phases.
The bootstrap fork is not one transaction
The richer client command can create a thread, create or select a worktree, run setup, and start the first turn. Those are several operations with compensating tombstone cleanup on failure. Only the two-to-four-event batch for an already existing thread—optional lifecycle resets, then message and turn-start—is decided and committed atomically.
The full causal loop
Zoom with the controls, +/−, or Ctrl/⌘ + trackpad scroll. Enable Pan to drag, use two-finger scrolling, or use the arrow keys. 0 fits the diagram; Esc leaves Pan or expanded view.
Text equivalent
An existing-thread command is authorized, normalized, serialized, decided, and atomically stored with its accepted receipt. The client receives only the committed sequence. A hot post-commit event starts provider work through ProviderService and an adapter. Canonical provider events independently feed runtime ingestion and optional checkpoint capture. Both return durable results by sending internal commands to the same engine. HTTP snapshots and WebSocket live events synchronize the client.
apps/server/src/orchestration/Normalizer.ts:46–178 ↗apps/server/src/orchestration/Layers/OrchestrationEngine.ts:197–259 ↗packages/contracts/src/orchestration.ts:1580–1583 ↗apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1060–1174 ↗apps/server/src/provider/Layers/ProviderService.ts:356–409 ↗apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts:1490–1874 ↗apps/server/src/orchestration/Layers/CheckpointReactor.ts:842–937 ↗apps/server/src/orchestration/Layers/CheckpointReactor.ts:270–316 ↗apps/server/src/ws.ts:1394–1521 ↗The diagram intentionally keeps the checkpoint worker in the reactor lane, but its last write does not bypass the domain kernel. Git capture is a side effect; the result becomes durable only after a new internal command passes through the engine.