Architecture overview

Read with: ttt-audit.md (what TTT really has), the ADRs in ../decisions/, the language specification, and the host API contract.

1. Layers and ownership#

                         TTT DESKTOP APPLICATION (trading-terminal/)
┌───────────────────────────────────────────────────────────────────────────┐
│ terminal-ui   t0_window.rs: editor, diagnostics, grants, output, status  │
│                 (plain display data only; reports actions)                │
│ terminal-app  owns the T0 session; services UI requests once per frame;   │
│               implements UiPort over its charts                           │
│ ─────────────────────────────── T0 HOST BRIDGE ─────────────────────────── │
│ t0-host       manifest + operation registry (descriptor + handler, once)  │
│               session: grants, executions, output, progress, cancel       │
│               providers: workspace (UI queue), market (datasets, candles),│
│               features (signal vocabulary), backtest (BacktestRunner)     │
│               strategy bridge: T0 signal graph → strategy_graph IR        │
│ ─────────────── existing TTT crates (unchanged by T0) ─────────────────── │
│ strategy-graph · strategy-runtime · backtest · replay · storage ·         │
│ strategy-workspace (DatasetLocator) · research-api · execution            │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │ path dependency, one way
┌───────────────────────────────▼───────────────────────────────────────────┐
│ T0 LANG (t0-lang/, independent Cargo workspace)                            │
│ t0-num       Decimal, financial values, time parsing                      │
│ t0-diag      spans, diagnostics, code registry                            │
│ t0-contract  versions, contract model, manifest, HostValue, permissions   │
│ t0-syntax    lexer, parser, AST                                           │
│ t0-ir        typed IR, dimension table, validator, artifact               │
│ t0-compiler  resolution, type checking, capability analysis, lowering     │
│ t0-runtime   reference interpreter, Host trait, limits, executions        │
│ t0-testkit   mock host, conformance harness                               │
│ t0-cli       `t0` command: check, build, validate, run, explain           │
└───────────────────────────────────────────────────────────────────────────┘

Rules:

• T0 crates never depend on TTT crates (ADR-0001).
• TTT-specific capabilities reach a program only through the host bridge, described by the manifest (ADR-0006). The compiler has no list of TTT functions.
• The bridge holds no domain logic: it validates, translates and dispatches to TTT's existing systems. Strategies run on TTT's engine (ADR-0004).
• terminal-ui gets display rows and returns actions, the pattern every window there already follows.

2. Execution topology#

work	where it runs
parsing, type checking, IR validation	a worker thread (the execution's, or a short-lived one for a check) — never the UI thread
interpreter (pure computation)	the execution's worker thread (ADR-0002)
workspace.* operations	queued to the UI thread, applied inside App::ui, answered to the worker (ADR-0003)
market.datasets	worker thread → DatasetLocator (HTTP to the backend catalogue) or a local datasets directory
market.candles	worker thread → replay::ReplaySource over a local dataset
backtest.run	worker thread → BacktestRunner::run_watched with a RunControl bound to the execution
remote research/backtest workers	[planned, Phase 9] behind the same contracts

The UI thread's per-frame cost is draining the UI-request queue and copying the session's snapshot (status, progress, output tail) into the window's shared state.

3. Lifecycle of a .tz program inside TTT#

3.1 Application start-up#

1. TTT starts as today. The T0 session is created when the application starts but does no work until the T0 window is used.
2. The bridge builds its manifest: every registered operation with its descriptor and its status — available (e.g. market.datasets needs a catalogue or a datasets directory), healthy (None until measured).
3. The window shows the language version, the host API version, and each contract with its status. A missing service never blocks the editor: checking still works; calls to an unavailable operation fail with E-CAP-UNAVAILABLE and the reason.

3.2 Opening and checking a program#

1. The user opens a .tz file or types into the editor.
2. Check compiles against the live manifest on a worker thread and shows diagnostics (code, line:column, message, help) and what the program needs: contracts with versions, and permissions.
3. Checking grants nothing and calls nothing on the host.

3.3 Running#

1. Run captures the source and the session's current grants.
2. Worker thread: compile → IR → independent IR validation → version compatibility (language, IR, host API, each contract) → required permissions ⊆ grants (else refused with E-PERM-DENIED naming each missing one) → availability of every used operation.
3. The interpreter executes main. Each host call re-checks the declared contract and the grant, is dispatched (inline, UI queue, or provider), and its result is converted and checked against the contract's return type.
4. Output (print), progress (from backtests) and the final outcome are published to the session; the window shows them each frame.

3.4 Termination#

case	outcome	cleanup
main returns	Completed with the returned value	thread ends
main returns Err(e)	Failed with e.code/e.message	thread ends
compile or validation error	Refused with diagnostics	nothing started
missing capability or version	Refused (E-CAP-*, E-VER-*)	nothing started
missing permission	Refused (E-PERM-DENIED)	nothing started
user presses Stop	Cancelled at the next step boundary; a running backtest sees should_cancel and ends StoppedByUser	worker thread ends; pending UI requests are answered E-HOST-CANCELLED
fuel / depth / collection / wall-time limit	Failed with E-RT-*	thread ends
interpreter panic	Failed with E-RT-INTERNAL	caught at the thread boundary
UI not servicing requests	that call fails with E-HOST-UI-TIMEOUT	the program may handle it
application shutdown	every execution cancelled; the app waits up to 2 s, then detaches	journals already written stay on disk, marked stopped

3.5 Session vs execution#

• Session: one per TTT process, owned by terminal-app. Holds grants (memory only), the manifest, the history of recent executions (bounded) and the editor state. Ends with the process.
• Execution: one run of one program. Identity ExecutionId (a process-unique counter). States Compiling → Running → {Completed, Failed, Cancelled, Refused}. Nothing — no variable, handle or subscription — survives from one execution to the next in v0.
• Host jobs started by an execution (backtests) belong to it and end with it. [planned] detached jobs that outlive an execution (backtest.submit returning a job handle), listed by the session.
• Handles carry the session epoch; one saved and reused after a restart fails with E-HOST-STALE-HANDLE.

4. Data flow of the first vertical slice#

.tz source ──► t0-compiler ──► IR artifact ──► t0-ir validator
                                                   │
                                                   ▼
                           t0-runtime (worker thread) ──► print / progress ──► session ──► T0 window
                                 │ host calls
                                 ▼
                             t0-host
          market.datasets ──► DatasetLocator / local dir
          backtest.run(spec) ─► strategy bridge ─► strategy_graph::validate/compile
                                                ─► BacktestRunner (TTT) ─► journal (runs dir)
                                                ─► Report ─► t0-runtime

5. Deliberately not in v0#

Native code generation (Phase 7), remote workers (Phase 9), live order submission (Phase 10), detached jobs, user generics/closures, multi-file modules, a language server. Each is in ../roadmap/implementation-phases.md with the condition for starting it.