+
+
+
+
+| Concern | Shell stream | Thread-detail stream |
|---|---|---|
| Projection | project/thread summaries for navigation | one thread's messages, activities, turns, plans, checkpoints, and session detail |
| Live optimization | 50 ms / 512-input window; last event per aggregate triggers a current-shell refetch | filtered detail events stream without shell coalescing |
| Replay cutoff | global gap 0…1,000 | global gap 0…1,000, then filter to the requested thread |
| Fallback | fresh shell snapshot | fresh thread snapshot, optionally windowed by negotiated turnLimit |
+
+
+
+
+All four environment-server posture rows advertise browser-cookie, Bearer, and DPoP session methods. The contract
+also defines `unsafe-no-auth`, but the policy implementation does not produce it at
+the pinned revision. A descriptor is capability and posture metadata; it is not an
+authorization bypass.
+
+| Runtime posture | Advertised policy | Bootstrap methods |
|---|---|---|
| desktop, local-only host | desktop-managed-local | desktop bootstrap |
| desktop, remotely reachable host | remote-reachable | desktop bootstrap + one-time token |
| web/server, local-only host | loopback-browser | one-time token |
| web/server, remotely reachable host | remote-reachable | one-time token |
+
+
+
+
+| Credential | Storage / binding | Default lifetime / acceptance window | Use behavior |
|---|---|---|---|
| desktop bootstrap seed | in-memory map; trusted process handoff | 24 hours | unbounded reuse while process state survives |
| ordinary pairing link | plaintext credential in SQLite row | 5 minutes | exactly one successful atomic consume |
| development startup link | plaintext credential in SQLite row | 24 hours | exactly one successful atomic consume |
| normal startup link | plaintext credential in SQLite row | 5 minutes | exactly one successful atomic consume |
| browser or Bearer session | server-signed token + SQLite session row | 30 days | reusable until expiry or revocation |
| DPoP access session | signed token with a jkt claim + SQLite session row; bound to a P-256 key | 1 hour | requires a valid token-bound proof per request |
| DPoP proof | signed JWT + exclusive replay-marker file | 5-minute acceptance window; 5-second future tolerance; no exp claim | one use for each thumbprint + jti |
| WebSocket ticket | server-signed ticket containing session id; row reloaded | 5 minutes | the pinned issue/verify path records no one-use state |
+
+
+
+
+| Path | Scope result | Expansion rule |
|---|---|---|
| desktop bootstrap seed | administrative set | seeded by the trusted desktop process |
| ordinary one-time link | standard set unless the issuer supplied another set | issuance policy owns the grant |
| startup link | administrative set | created by server startup |
| browser-session exchange | the complete grant set | the browser path does not request a narrower subset |
| Bearer or DPoP token exchange | requested subset, or the grant set by default | cannot add a scope absent from the grant |
| session delegates another pairing link | nonempty, unique requested subset | issuer needs access:write and must hold every delegated scope |
+
+
+
+
+| Field | Meaning | Reading rule |
|---|---|---|
sequence | global durable order assigned by SQLite | resume and projection cursors compare this value across all aggregates |
eventId | unique event identity allocated by the decider | identity is not the ordering mechanism |
aggregateKind + aggregateId | project or thread stream owning the fact | these also define the accepted receipt's aggregate binding |
type + payload | the domain fact and its variant-specific data | projectors switch on the type; the payload is not stored in the command receipt |
occurredAt | domain timestamp selected during decision | do not use it as a replacement for global sequence order |
commandId | command that caused the event, or null | several events can share one command id |
causationEventId | direct event-level cause where one is known | for a turn start, the request event points at the user-message event |
correlationId | command-level correlation, normally the command id | groups a batch without replacing event identity |
metadata | provider ids, adapter key, request id, ingestion time, and optional client origin | metadata carries attribution and integration context, not aggregate state itself |
stream_version and infers an
+ actor_kind column while inserting. The decoded public event returned by
+ this store contains the global sequence and envelope fields above, but not either
+ storage column. Actor classification is inferred from command-id prefixes and
+ provider metadata; it is not a claim supplied as a public event field.
+
+
+
+
+
+An accepted same-aggregate retry does **not** replay the original events into the hot
+stream. It returns the stored sequence immediately. This is desirable after a lost
+RPC response when the original publication completed. It cannot repair a
+commit-to-publication crash gap.
+
+| Stored receipt | Retry aggregate | Engine result | New events / publication |
|---|---|---|---|
| accepted | same kind + id | return stored resultSequence | none / none |
| accepted | different kind or id | command-id conflict | none / none |
| rejected | same kind + id | previously-rejected error with stored detail | none / none |
| rejected | different kind or id | command-id conflict | none / none |
| no row | any | decide against current state | depends on current decision |
+
+
+
+
+| Boundary reached | What is established | What is still not established |
|---|---|---|
| SQL commit | event batch, synchronous projections, accepted receipt | hot publication and any reactor work |
| PubSub loop completes | every event was offered to current in-memory subscribers | durable delivery or completed reactor handling |
RPC returns {`{ sequence }`} | server exposes the last durable event sequence | that the response reached the client |
| client receives sequence | client knows its durable intent was accepted | provider process start, token output, or turn completion |
| provider lifecycle events arrive | the corresponding later provider milestone | milestones not yet represented by a later event |
thread.turn-start-requested later and sends work through its
+ own worker/forked path. The returned sequence therefore proves durable domain
+ intent, not provider acceptance, execution, or completion.
+RuntimeReceiptBus is a test synchronization hook
+ for runtime ingestion; its production layer is a no-op. It does not deduplicate
+ commands, close the PubSub crash gap, or strengthen the RPC acknowledgement.
+
+
+
+
+
+| Reader | Purpose | What it intentionally leaves out |
|---|---|---|
| Full hydrated snapshot | authoritative composed read for complete state | nothing from its selected projection families; it is the expensive shape |
| Command read model | engine bootstrap and command decisions | messages, activities, and checkpoints |
| Shell snapshot | project/thread navigation and live shell refetches | thread bodies, activity history, plans, checkpoint/turn detail |
| Thread detail snapshot | one selected conversation, optionally windowed | older turn windows beyond its cursor until requested |
+
+
+
+
+Calling this “serialized provider execution” would be wrong. The provider reactor's
+queue orders the start of its handler bodies. At `ProviderCommandReactor.ts:1171–1173`,
+`sendTurn` is forked, so two provider sends can overlap. First-turn title and branch
+work are also forked. Other reactors may concurrently process the same domain or
+provider event through their own subscriptions.
+
+| Consumer | Serialized body | Work outside that body | Restart behavior |
|---|---|---|---|
| provider command | domain-event handler dequeue | sendTurn, first-turn branch naming, and title work are scoped forks | fresh hot subscription; volatile dedupe disappears |
| runtime ingestion | runtime events plus selected domain inputs; the current domain handler is a no-op | buffer timers and internal commands cross back into the engine | source audit found no durable runtime-event cursor; selected activity lookup is a narrow fallback |
| checkpoint | capture/revert trigger handling | Git refs, workspace mutation, provider rollback, then internal commands | source audit found no replay of a missed hot trigger or durable saga phase |
| thread deletion | one deletion side-effect handler at a time | provider stop and terminal cleanup touch separate systems | source audit found no startup scan for a missed deletion event |
| awareness | awareness event handling | delayed confirmation fibers and relay publication | re-emits current active state, not the missing event history |
+
+
+
+
+| Claim | Evidence | Classification |
|---|---|---|
| a later projector failure rolls back a multi-event transaction | OrchestrationEngine.test.ts:906–1024 | tested |
| the command worker continues after an append failure | OrchestrationEngine.test.ts:781–904 | tested |
| retrying one genuine command id returns its stored accepted sequence | OrchestrationEngine.test.ts:1234–1296 | tested |
| one worker drain waits for subsequently enqueued counted work | DrainableWorker.test.ts:8–56 | tested |
| hard crash between commit and first PubSub publish is repaired | no process-crash test and no outbox/cursor implementation | not guaranteed |
| same id + same aggregate + changed payload conflicts | receipt has no type/payload fingerprint; no matching test | not guaranteed |
| shutdown drains forked provider sends | fork is outside the worker counter; no production drain test | not guaranteed |
| replaying an identical provider event is a no-op | generated internal id includes random UUID; no crash/replay test | not guaranteed |
+
+
+
+
+| Migration | Durable role | Important boundary |
|---|---|---|
001 orchestration events | append-only event envelopes with stream versions | unique event id and aggregate-version pair |
002 command receipts | accepted/rejected result lookup by command id | no command type or payload fingerprint |
004 provider bindings | provider instance, native session id, and resume cursor | external provider state is not in the same transaction |
005 projection tables | projects, threads, messages, activities, sessions, turns, and per-projector cursor | deleted projects/threads use tombstones |
007 attachment references | JSON metadata in projection rows | image bytes remain separate files |
013 plans | durable plan projection | later migrations refine linkage and shape |
+
+
+
+
+The event-store API exposes append and reads, not event-history deletion. The receipt
+repository exposes upsert/get, not a retention pass. Provider-binding deletion exists
+in the repository interface, but a pinned-source search found no production caller;
+that is an absence-of-code inference, not a permanent product promise.
+
+## What startup repairs
+
+| Mechanism | What changes | What remains |
|---|---|---|
| project/thread deletion | sets SQL deleted_at; shell queries omit tombstoned rows | events, receipts, and tombstoned rows remain; the inspected handler does not delete provider bindings or hidden refs |
| thread revert | prunes selected derived messages, plans, activities, turns, attachment files, and newer checkpoint refs | the append-only orchestration event history and revert events |
| provider/terminal log retention | rotates, caps, or evicts independent log/history files | SQLite domain history unless a separate domain operation changes it |
| in-memory fold caps | limits current message/checkpoint collections in memory | SQL rows; the cap is not database garbage collection |
+
+
+
+
+## Evidence and missing crash tests
+
+| Timing | State | Limit |
|---|---|---|
| before server boot | restore-marker-directed recovery of an interrupted SQLite-triplet rollback | only named database files |
| eager | migrations, projector cursors, optimized command model | projector read defaults to 1,000 total events |
| eager best-effort | projected active provider sessions missing from live adapter inventory become stopped/error | retry once; does not replay the original turn |
| delayed/current-state | agent awareness republishes active threads after activation | not historical event replay |
| lazy | provider binding adoption/resume and terminal text restoration | requires a later routed operation or first terminal open |
| not generally reconciled in the source audit | missed reactor jobs, attachment orphans, ref/SQL pairs, settings/secret pairs | no general startup pass was found; later incidental operations may still converge selected state |
+
+
+
+
+| Area | Covered | Still missing |
|---|---|---|
| SQLite | concurrent writer waits; selected migration upgrades | power loss, WAL checkpoint policy, crash halfway through the full runner |
| projection bootstrap | three-event fold and repeat-at-cursor idempotency | 1,001-event tail and serving while a projector remains behind |
| service updater | prepared-before-commit, id validation, main/WAL/SHM rollback | kill and restart at every marker/restore/state-write edge |
| settings/secrets | redaction, roundtrip, races, file permissions | crash between secret mutation and JSON replacement; malformed-file repair |
| attachments | real revert cleanup and SQL rollback | orphan collection, external delete followed by outer rollback, crash after cursor advance |
| terminal | normal persistence, sanitizer, cap, eviction, migration | torn overwrite, hard crash in debounce window, general-scope drain |
| checkpoints | diffs and basic hidden-ref behavior | staging-boundary roundtrip, orphan-ref startup repair, crash during revert saga |
+
+
+
+
+“Client” and “internal” are admission boundaries, not a complete actor history.
+Events later infer an actor class from command-id prefixes and provider metadata.
+Do not interpret the internal union as “commands that are not serialized” or
+“commands that bypass invariants”: both dispatchable client commands and trusted
+internal commands enter the engine's command union.
+
+| Shape | Who can construct it | What changes before the next boundary |
|---|---|---|
ClientOrchestrationCommand | authenticated HTTP or WebSocket client | timestamps, workspace paths, and attachment data still need server normalization; turn start may include bootstrap instructions |
DispatchableClientOrchestrationCommand | server after client normalization | raw attachment data has become persisted attachment metadata; the shape is ready for the domain engine |
InternalOrchestrationCommand | trusted server/provider reactors | assistant deltas, sessions, plan updates, activities, diff completion, and similar runtime results re-enter the same domain engine |
orchestration:operate, then normalizes its
+ payload. WebSocket RPC authorization likewise checks the method's required scope
+ before the dispatch handler normalizes the command. Internal reactor dispatch is a
+ separate trusted path; it is not made client-reachable by belonging to the engine
+ union.
+sql.withTransaction. If a persistence
+ failure leaves no receipt, a retry decides again and may allocate different event
+ identifiers or times even though the command id is unchanged.
+
+
+
+
+
+| Question | Decision | Why it belongs here |
|---|---|---|
| Does the target thread exist? | missing thread rejects the command | the serialized model is authoritative at decision time |
| Was a proposed plan named? | the referenced plan must exist on its source thread | a structurally valid id is not proof that the plan is present |
| Does that plan cross projects? | source and target thread must belong to the same project | the decider can inspect related aggregates in one model |
| Was the target settled or snoozed? | emit lifecycle-reset events before message and turn intent | valid activity evolves state; it is not always a rejection |
thread.turn.start case calls the general thread-presence check,
+ not the explicit “not archived” helper. The executable case shown here therefore
+ does not support that blanket invariant. Treat it as a source discrepancy to test,
+ not as a guaranteed rule.
+thread.delete. The shown failure
+ path contains no worktree or branch removal. That is an absence-of-code inference
+ at the pinned revision, not a promise that future cleanup will remain narrow.
+thread.turn.start with bootstrap to run the
+ create/worktree/setup saga. Sending that payload over HTTP does not execute the
+ WebSocket bootstrap choreography.
+
+
+
+
+
+`sendTurn` returns `ProviderTurnStartResult`: a T3 `threadId`, a `turnId`, and an
+optional opaque resume cursor. It does not return generated text. Text, tool
+activity, plan changes, requests, usage, completion, and failures arrive later on
+`streamEvents`.
+
+| Responsibility | Members | Immediate meaning | Not implied |
|---|---|---|---|
| Session lifecycle | startSession, stopSession, listSessions, hasSession, stopAll | manage adapter-owned live sessions keyed by T3 thread id | that native state is stored in the orchestration transaction |
| Turn control | sendTurn, interruptTurn | request a native turn start or interruption | assistant output or completed interruption |
| Human interaction | respondToRequest, respondToUserInput | resolve a pending native approval or structured-input request | that every provider can originate both request kinds |
| Conversation state | readThread, rollbackThread | read or mutate the provider's own thread representation | that rollback has identical semantics or support everywhere |
| Optional extension | uploadFeedback? | provider-specific feedback upload when present | a negotiated generic extension mechanism |
| Output | streamEvents | one canonical hot runtime-event stream | durable replay, delivery acknowledgement, or provider conformance to every event variant |
steer member in the SPI. A provider can interpret
+ sendTurn while a turn is already active as steering—OpenCode has a
+ concrete tested implementation—but the generic contract alone promises only a
+ send request. Chapters 16–19 document each adapter's behavior separately.
+sessionModelSwitch: "in-session" at the pinned commit. The
+ unsupported branch is real reactor logic and part of the contract,
+ but it is not a current five-provider difference.
+
+
+
+
+
+One naming wrinkle matters: the live adapter facade currently reports a missing or
+unavailable instance as `ProviderUnsupportedError`, even though a separate
+`ProviderInstanceNotFoundError` type exists. The book follows executed paths, not
+just exported class names.
+
+## Walk the contract boundary
+
+Choose an operation and advance its round trip. The moving token stops at the
+immediate return boundary before continuing along the independent runtime-event
+lane. Try sending while a turn is already running: the lab deliberately refuses to
+label that generic call “steer,” because only each concrete adapter can settle that
+meaning.
+
+| Boundary | Typed families | What the distinction preserves |
|---|---|---|
| Adapter | validation, session-not-found, session-closed, request, process | bad T3 input is different from a missing native session, protocol failure, or dead process |
| Driver construction | ProviderDriverError | a configured instance can become an unavailable UI shadow without crashing server boot |
| Registry/service | unsupported, instance-not-found, session-not-found, directory persistence, validation | routing/configuration failure remains distinct from native adapter failure |
+
+
+
+
+`ProviderDriverKind` is intentionally not a closed five-literal union. The shipped
+build registers Codex, Claude, Cursor, Grok, and OpenCode, but settings and persisted
+state can outlive a build, move between forks, or refer to a driver that is absent
+after rollback. Schema decoding accepts any valid slug; the runtime makes absence
+visible.
+
+| Identity | Example | Owner and role | Routing key? |
|---|---|---|---|
| Driver kind | codex | open branded slug selecting implementation, config decoder, probe, adapter, and text generation | No; it verifies implementation and names the default legacy instance |
| Instance id | codex_work | user-defined slug naming one materialized configuration and its scoped closures | Yes |
| Discovery snapshot | models, auth state, health | UI-facing observation for one instance; cached and refreshed independently | No; its instanceId field points back to the route |
| Native account | provider email or login | provider-reported observation; may affect access and models | No |
| T3 thread id | thread_… | durable product conversation/work item | Entry to the persisted binding lookup |
| Native session id | app-server, SDK, ACP, or ses_… | adapter/provider-owned continuation identity | No; wrapped in an opaque resume cursor |
| Continuation key | codex:instance:codex_work | driver-defined compatibility group used when deciding whether a session may continue across instance changes | No; a compatibility predicate |
instanceId as its stable routing identity.
+ The live adapter facade resolves only by instance id. Its legacy
+ listProviders view merely lists driver kinds whose default instance
+ currently exists; it does not restore kind-based routing for custom instances.
+supportsMultipleInstances: false and the registry will reject a
+ duplicate configuration. At the pinned commit, all built-ins permit multiple
+ instances and the inspected registry reconciliation path never reads that field.
+ Treat it as documented intent, not an enforced runtime guarantee.
+serverPassword as stored in plain
+ text on disk; its password-shaped UI input is not encryption. When an external
+ OpenCode URL is configured, the adapter passes that value as Basic
+ authentication. A locally launched managed OpenCode server follows a different
+ process-ownership path.
+
+
+
+
+
+The rollback row is intentionally asymmetric. Cursor’s implementation removes entries
+from its local `ctx.turns` array; source inspection does not find a Cursor ACP native
+revert call in that method. That changes the adapter’s read snapshot, not necessarily
+the provider’s remote history. Grok refuses the operation explicitly. Orchestration
+revert still has its own durable events and projection cleanup (Chapter 13); neither
+adapter row should be read as a transaction across that durable model and native
+provider state.
+
+| Concern | Cursor adapter | Grok adapter |
|---|---|---|
| launch | cursor-agent … acp; optional endpoint | grok agent stdio; XAI auth/referrer setup |
| resume | passes a versioned Cursor session id to the shared ACP runtime | passes a versioned Grok session id to the same load-or-new path |
| mode/model | model plus config-option mode heuristic from discovered mode state | compares setup model then calls ACP session/set_model when needed |
| plan/input extensions | Cursor plan/todo/question extensions receive bespoke mappings | XAI ask-user extension receives bespoke mapping; ordinary ACP updates can still carry plans |
| running second prompt | reuses active turn id; only the last prompt completion settles it | same intent, with turn-target-aware settlement and interrupted-turn suppression |
| interrupt | cancels ACP and resolves pending approval/input waits | marks a target as interrupted before the lock, filters late notifications, then cancels and settles slots |
| rollback | emulates local rollback by truncating its in-memory turn snapshot | explicitly unsupported: returns a provider request error; no provider-side rollback is invoked |
+
+
+
+
+An absence cell means no implementation branch was found at this pinned revision;
+it does not claim the upstream product can never expose that feature. Chapters 16,
+17, and 20 provide the longer Codex, Claude, and usage trails. The matrix keeps
+provider discovery (skills/commands), live adapter normalization (plans/tasks and
+context telemetry), and the independent transcript scanner in separate rows so one
+surface cannot masquerade as another.
+
+| Operation | Codex | Claude | Cursor | Grok | OpenCode |
|---|---|---|---|---|---|
| transport | native app-server JSON-RPC mapping | native Agent SDK stream mapping | native ACP stdio mapping | native ACP stdio + XAI extension mapping | native SDK/HTTP event mapping |
| resume | adapter passes a Codex resume cursor to app-server runtime | adapter uses SDK resume metadata | adapter passes native session id to ACP load/new flow | adapter passes native session id to ACP load/new flow | a recognized cursor re-adopts sessionId; confirmed miss starts fresh; absent/malformed/wrong-version cursor means no resume; cwd change forks |
| mid-turn send | calls native turn/start; app-server may queue a new native turn id while interrupt still targets the current one | queues into the live SDK loop and reuses the active product turn id | reuses active product turn while prompts are in flight | reuses active turn with target-aware settlement | calls promptAsync and reuses active product turn |
| approval/input | native JSON-RPC requests mapped to canonical request/input events | SDK-side deferred interactions mapped to canonical request/input events | ACP permission + Cursor question extension mapping | ACP permission + XAI question extension mapping | native permission/question events mapped; replies call SDK endpoints |
| plans, tasks, subagents | native plans plus multi-agent signals become plan and task.* events | TodoWrite, coordinator, and member observations become plan and task.* events | Cursor plan/todo extensions become plan events; no task.* emission branch found | ACP plan observations become plan events; no task.* emission branch found | plan mode selects a native agent and task-like tools become item activity; no plan or task.* emission branch found |
| commands and skills discovery | snapshot requests native skills and adds a feedback slash command | snapshot combines initialization commands with discovered filesystem skills | snapshot exposes models/probe state; no skills or slash commands found | snapshot exposes models/probe state; no skills or slash commands found | provider inventory exposes skills; no slash commands found |
| live context telemetry | emits canonical token-usage snapshots | emits canonical token-usage snapshots when normalization succeeds | no canonical token-usage emission branch found | no canonical token-usage emission branch found | no canonical token-usage emission branch found |
| historical Usage source | Codex JSONL session transcripts are scanned | Claude JSONL project transcripts are scanned | not scanned | not scanned | not scanned |
rollbackThread behavior | native app-server rollback mapping | adapter-local turn snapshot truncation plus resume-cursor refresh | adapter-only local snapshot truncation | explicitly unsupported | native session.revert mapping |
| in-session model switch | declared SPI capability: in-session | declared SPI capability: in-session | declared SPI capability: in-session | declared SPI capability: in-session | declared SPI capability: in-session |
| failure projection | typed process/protocol/request failures plus runtime warning/error events | typed SDK/request failures plus terminal result classification | typed ACP failures plus provider-specific callback and cancel handling | typed ACP failures plus late-event suppression around interruption | typed SDK/HTTP failures; when probing a recognized cursor, only confirmed not-found permits fresh-session replacement |
+
+
+
+
+| Adapter | Provider-side input | Canonical emission boundary | Coverage qualification |
|---|---|---|---|
| Codex | native thread/tokenUsage/updated notification | CodexAdapter normalizes it, rejecting a non-positive usedTokens | emitted when that native notification arrives; total processed is read from native total, current use from native last |
| Claude | normalized Claude SDK message / task-progress usage | emitThreadTokenUsage | emitted only when normalization produced usage; the adapter remembers its last known values |
| Cursor, Grok, OpenCode, ACP adapters | no canonical emission branch found in this revision | — | absence in this audit is not evidence that a provider can never expose usage; it means this build does not project it through this event |
thread.turn.start after its event batch and
+ receipt commit, before ProviderService.sendTurn runs. This is
+ intentionally narrower than provider acceptance or turn completion.
+thread.token-usage.updated, while historical
+ accounting reads provider transcript sources. No inspected accumulator joins the
+ task rollup into either Chapter 20 total; that negative conclusion is bounded to
+ these concrete paths.
+git clean -fd, then resets the index path when HEAD
+ exists. The final index is therefore not a preserved staging snapshot of the
+ checkpoint. Untracked non-ignored files under the workspace can disappear. Review
+ a diff before requesting a revert; do not treat it as an undo stack for remote
+ commits, pushes, or external provider state.
+isElectron branch alone
+ does not prove that the selected environment is local, connected, online, or
+ authoritative for a particular thread.
+
+ 
+
+ # T3 Code Decoded
+
+ **A source-grounded, interactive guide to the architecture and implementation of T3 Code.**
+
+ [Read the book](#read-the-book) · [Explore the plan](./BOOK_PLAN.md) ·
+ [Contribute](./CONTRIBUTING.md) · [Source policy](#source-grounding)
+
+
+> [!IMPORTANT]
+> This is an independent, unofficial study guide. It is not maintained or endorsed
+> by Ping Labs or the T3 Code maintainers. Product behavior is described at one
+> pinned source revision and may change upstream.
+
+Created and maintained by [Ahmed Alaa (`@BenAlaa`)](https://github.com/BenAlaa).
+
+> [!NOTE]
+> The public Pages site is deployed from protected `main`. It reflects the latest
+> merged revision; topic branches remain local or unmerged until their reviewed
+> pull requests are ready.
+> No authored work is pushed directly to `main`.
+
+## Read the book
+
+[Read the published book](https://benalaa.github.io/t3code-decoded/). When reviewing
+an unmerged change, run that branch locally with the instructions below—the
+published site intentionally tracks protected `main`, not unpublished work.
+
+The current edition is pinned to
+[`pingdotgg/t3code@fa219001d`](https://github.com/pingdotgg/t3code/tree/fa219001dc2f14cfd9c7774c2c03c153359144be).
+Every exact excerpt in the book is generated from that revision, checksum-verified,
+and linked back to immutable GitHub source lines.
+
+## What this book explains
+
+T3 Code is not the reasoning engine inside Codex, Claude, Cursor, Grok, or
+OpenCode. It is the server-authoritative control plane around them: it normalizes
+intent, durably records product state, starts and supervises provider runtimes,
+projects ordered state to several clients, and surrounds the conversation with
+worktrees, Git checkpoints, terminals, files, previews, remote access, usage, and
+distribution machinery.
+
+```text
+Web · Desktop · Mobile
+ │ typed, authenticated Effect RPC
+ ▼
+T3 server: command → event → projection → reactor
+ │ │
+ │ └─ files · Git · terminal · tunnel
+ ▼
+ProviderAdapter
+ │ native protocol
+ ▼
+Codex · Claude · Cursor · Grok · OpenCode
+```
+
+The book follows that causal path instead of mirroring repository folders. Its
+eight parts cover:
+
+1. ownership boundaries, vocabulary, repository topology, and runtime shapes;
+2. CLI/server boot, Effect RPC, pairing, authorization, subscriptions, and resume;
+3. commands, events, receipts, projections, reactors, SQLite, and recovery;
+4. the provider adapter contract, all five harness integrations, and both usage
+ systems;
+5. projects, worktrees, turns, permissions, plans, tasks, context, memory,
+ checkpoints, terminals, files, VCS, MCP, preview, and pull requests;
+6. the shared client runtime plus web, Electron, and React Native clients;
+7. direct/relay/Tailscale/SSH access, reconnection, packaging, releases, updates, and telemetry;
+8. complete end-to-end traces, architectural trade-offs, limitations, and
+ evidence-bounded roadmap analysis.
+
+See [BOOK_PLAN.md](./BOOK_PLAN.md) for the complete 40-chapter specification,
+figure/lab inventory, review gates, and definition of done.
+
+## Why another set of docs?
+
+The upstream documentation is primarily a product and operations guide. This book
+answers a different class of questions:
+
+- Where is the transaction boundary?
+- What does a command receipt actually prove?
+- Which state survives a server restart?
+- How do five provider protocols become one product vocabulary?
+- Why does reconnect logic live above a one-attempt RPC session?
+- What is shared across clients, and what deliberately differs?
+- Which remote component allocates credentials, and where does application traffic
+ really flow?
+- Which capabilities ship today, exist only in builders/contracts, or are explicit
+ future work?
+
+The explanations include failure windows and discrepancies where prose, comments,
+contracts, code, and release automation do not agree.
+
+## Source grounding
+
+The repository treats evidence as build input rather than editorial decoration.
+
+| File | Role |
+| --- | --- |
+| [`sources/t3code.lock.json`](./sources/t3code.lock.json) | Immutable upstream revision and inventory |
+| [`sources/excerpts.manifest.json`](./sources/excerpts.manifest.json) | Exact source ranges selected by authors |
+| [`sources/references.manifest.json`](./sources/references.manifest.json) | Pinned file, directory, test, workflow, and documentation anchors |
+| [`src/generated/excerpts.json`](./src/generated/excerpts.json) | Generated code, line numbers, and SHA-256 checksums |
+| [`scripts/sync-source-excerpts.mjs`](./scripts/sync-source-excerpts.mjs) | Extraction and source-revision guard |
+| [`scripts/validate-sources.mjs`](./scripts/validate-sources.mjs) | Manifest/generated-integrity validation |
+
+Claims use four explicit classes:
+
+- **Verified behavior** — backed by executable code, tests, schema, migration, or
+ workflow at the source lock.
+- **Documented intent** — backed by a pinned upstream document.
+- **Inference** — a named interpretation with every input cited.
+- **Future / proposed** — explicitly unshipped; never presented as current behavior.
+
+Mechanisms are also classified by durability: transactional, durable but
+eventually reconciled, provider-owned and resumable, ephemeral, or best effort.
+This matters especially for post-commit reactors, live agent state, checkpoints,
+and provider rollback.
+
+## Interactive reading experience
+
+The book is a static Astro site with focused interactivity rather than a client-side
+application shell:
+
+- clean, linkable chapter and heading routes;
+- typed MDX content and one authoritative content manifest;
+- full-text Pagefind search with a development fallback;
+- light, dark, and system themes;
+- keyboard-accessible navigation and simulations;
+- source cards with exact line numbers, checksums, copy, and immutable permalinks;
+- lazy diagrams with mouse/trackpad zoom, two-axis pan, drag, and expanded focus mode;
+- route-local, keyboard-operable labs with static and print fallbacks;
+- responsive layouts, reduced-motion behavior, and print styles;
+- base-path-aware URLs for GitHub Pages.
+
+The supplied book cover is reused directly; the site does not generate or alter it.
+
+## Repository layout
+
+```text
+.
+├── src/content/book/ # ordered MDX chapters
+├── src/components/ # figures, source cards, and interactive labs
+├── src/layouts/ # book shell and metadata
+├── src/styles/ # tokens, reading layout, print/responsive rules
+├── src/generated/ # checked-in exact source excerpts
+├── sources/ # upstream lock, excerpt manifest, and reference manifest
+├── scripts/ # source, content, search, and link validation
+├── tests/ # source-pipeline and book invariants
+├── .github/ # quality, Pages, issue, PR, and governance workflows
+└── BOOK_PLAN.md # editorial architecture and delivery gates
+```
+
+## Local development
+
+### Requirements
+
+- Node.js 24.10 or newer
+- npm
+- Git
+- Optional: a sibling checkout of `pingdotgg/t3code` at the pinned commit when
+ refreshing or independently verifying excerpts
+
+### Start the book
+
+```sh
+git clone https://github.com/BenAlaa/t3code-decoded.git
+cd t3code-decoded
+npm ci
+npm run dev
+```
+
+The development server prints its local URL.
+
+### Run the quality gates
+
+```sh
+npm run source:check
+npm test
+npm run build
+```
+
+`npm run build` validates content and generated evidence, creates the static Astro
+site, and builds its Pagefind index.
+
+### Verify against the upstream checkout
+
+Clone T3 Code beside this repository, or point `T3CODE_SOURCE_DIR` at an existing
+checkout:
+
+```sh
+git clone https://github.com/pingdotgg/t3code.git ../t3code
+git -C ../t3code checkout fa219001dc2f14cfd9c7774c2c03c153359144be
+npm run source:check
+```
+
+To intentionally refresh generated excerpts after editing the manifest:
+
+```sh
+npm run source:sync
+```
+
+Never refresh against a different upstream commit without updating the source lock
+as a dedicated, reviewed change.
+
+## Contributing
+
+Contributions are welcome for source corrections, clearer explanations, diagrams,
+simulations, tests, accessibility, and new evidence discovered at the pinned
+revision. Start with [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+The short version:
+
+1. open or find an issue for material architectural changes;
+2. branch from `main`—direct pushes are protected;
+3. make focused commits using [Conventional Commits](https://www.conventionalcommits.org/);
+4. keep excerpts generated and every material claim source-linked;
+5. run `npm test` and `npm run build`;
+6. open a pull request with a Conventional Commit title and the repository template;
+7. resolve review conversations and obtain the required approval before merge;
+ the owner may use the audited pull-request-only bypass for a solo-maintained PR.
+
+Chapter corrections should not be bundled with unrelated engine refactors. A book
+part may be one review milestone, but its chapters should remain fine-grained
+commits so reviewers can inspect the evidence and narrative separately.
+
+## Branch and release policy
+
+`main` is the only default line—there is no duplicate `master` branch. It is
+protected by pull-request review, passing book checks, resolved review
+conversations, and force-push/deletion restrictions.
+
+`BenAlaa` is the sole owner and initial reviewer. The ruleset grants that account
+**pull-request-only** bypass so solo maintenance remains possible without allowing
+routine direct pushes: an owner-authored change still needs a PR and leaves its
+review and bypass trail on GitHub. Contributions from everyone else require the
+configured approval.
+
+GitHub Actions deploys the exact validated `main` artifact to GitHub Pages. Build
+output is never committed to the source branch. Source updates, engine changes, and
+book-part milestones are reviewed as separate pull requests.
+
+## Attribution and trademarks
+
+T3 Code source excerpts are taken from
+[`pingdotgg/t3code`](https://github.com/pingdotgg/t3code), which is distributed
+under the MIT License. Each excerpt links to its immutable upstream revision.
+
+“T3 Code,” Ping Labs, Codex, Claude, Cursor, Grok, OpenCode, GitHub, and other
+names and marks belong to their respective owners. Their use here is descriptive.
+This project does not imply affiliation or endorsement.
+
+## License
+
+- Site engine, scripts, and original code: [MIT](./LICENSE-CODE)
+- Original book prose and diagrams: [Creative Commons Attribution 4.0](./LICENSE-CONTENT)
+- Upstream excerpts: their original MIT license and notices apply
+- Supplied cover artwork: included as a project asset but excluded from both grants
+
+See [NOTICE.md](./NOTICE.md) for the exact attribution boundary.
+
+## Security and conduct
+
+Please use the private reporting path in [SECURITY.md](./SECURITY.md) for a genuine
+security issue. Community participation follows [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
From 9d5450c43b13d523197f2694f132bd772c2c37c8 Mon Sep 17 00:00:00 2001
From: Ahmed Alaa <46384841+BenAlaa@users.noreply.github.com>
Date: Mon, 24 Aug 2026 13:27:28 +0300
Subject: [PATCH 11/12] test(book): add publication quality gates
---
tests/book-shell.test.mjs | 31 +++++
tests/built-site-validator.test.mjs | 21 +++
tests/change-metadata.test.mjs | 28 ++++
tests/diagram-explorer.test.mjs | 43 ++++++
tests/domain-core-labs.test.mjs | 121 ++++++++++++++++
tests/part-05-work-lifecycle.test.mjs | 115 ++++++++++++++++
tests/part-06-client-architectures.test.mjs | 105 ++++++++++++++
tests/part-07-reach-ship.test.mjs | 144 ++++++++++++++++++++
tests/part-08-synthesis.test.mjs | 135 ++++++++++++++++++
tests/provider-harness-labs.test.mjs | 124 +++++++++++++++++
tests/source-pipeline.test.mjs | 77 +++++++++++
11 files changed, 944 insertions(+)
create mode 100644 tests/book-shell.test.mjs
create mode 100644 tests/built-site-validator.test.mjs
create mode 100644 tests/change-metadata.test.mjs
create mode 100644 tests/diagram-explorer.test.mjs
create mode 100644 tests/domain-core-labs.test.mjs
create mode 100644 tests/part-05-work-lifecycle.test.mjs
create mode 100644 tests/part-06-client-architectures.test.mjs
create mode 100644 tests/part-07-reach-ship.test.mjs
create mode 100644 tests/part-08-synthesis.test.mjs
create mode 100644 tests/provider-harness-labs.test.mjs
create mode 100644 tests/source-pipeline.test.mjs
diff --git a/tests/book-shell.test.mjs b/tests/book-shell.test.mjs
new file mode 100644
index 0000000..02348b8
--- /dev/null
+++ b/tests/book-shell.test.mjs
@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const bookLayout = await readFile(new URL("../src/layouts/BookLayout.astro", import.meta.url), "utf8");
+const baseLayout = await readFile(new URL("../src/layouts/BaseLayout.astro", import.meta.url), "utf8");
+const styles = await readFile(new URL("../src/styles/global.css", import.meta.url), "utf8");
+
+test("book shell keeps chapter navigation in a reserved fixed dock", () => {
+ assert.match(bookLayout, /
+
+ # T3 Code Decoded
+
+ **A source-grounded, interactive guide to the architecture and implementation of T3 Code.**
+
+ [Read the book](#read-the-book) · [Explore the plan](./BOOK_PLAN.md) ·
+ [Contribute](./CONTRIBUTING.md) · [Source policy](#source-grounding)
+