# TOAST Architecture and Performance Contract

Every implementation pass must begin by reading this document together with
`AGENTS.md` or `CLAUDE.md`. The plan for the pass must state how the proposed
work satisfies this contract before runtime code is changed.

## Prime directive

> Functionality that is not active must cost practically nothing.

When all TOAST windows are closed, only strictly necessary communication and
game-state observation may consume CPU. Visualization code must be asleep.

## Runtime layers

### Always-on kernel

Keep the always-on surface deliberately small. It may receive the addon
protocol, observe state that must remain correct while the UI is closed, own
canonical crew state, and enforce release policy. Always-on does not mean
continuous polling: prefer specific game events and perform no work when an
event is irrelevant.

### Activity-scoped services

Queues, transfers, retries, cleanup, debouncing, bridge work, and animations
start when their first unit of work appears and stop after their last unit of
work completes. Every timer, ticker, event, hook, or `OnUpdate` must have an
explicit owner, activation condition, and stop condition.

### View-scoped UI

Build frames lazily on first use. A hidden view must not refresh, sort, scan,
normalize, render, or animate. Conceptually each view follows this lifecycle:

1. `Build` once on first use.
2. `Activate` only the events and interaction needed while visible.
3. `Refresh` only dirty data, layout, or selection.
4. `Deactivate` timers, drivers, and view-only events when hidden.

The functions do not need these exact names, but the lifecycle must remain
clear in the design.

## Hard rules

- Do not use a permanent `OnUpdate` for inactive functionality.
- Prefer game events as logical triggers. Use time only when behavior is
  genuinely time-bound.
- A temporary driver starts with the first task and stops with the last task.
- Do not keep a periodic cleanup ticker alive while all owned registries are
  empty.
- Coalesce bursty state changes before repainting an open view.
- Do not refresh a hidden view; its next `Show` performs the required refresh.
- Avoid temporary tables and closures in per-frame or high-frequency paths.
- Keep one canonical dataset. Build derived indexes lazily or invalidate them
  explicitly instead of maintaining competing copies.
- Cache expensive normalization, sorting, and chart preparation until their
  inputs change.
- Do not optimize cold-path loops merely for style. Complexity must buy a
  measured or structurally clear runtime benefit.
- Permanent background activity requires a documented architectural reason.

## Required pre-pass review

Before implementation, the plan must answer:

1. What is built or registered at addon load?
2. What remains active when the feature is unused or its view is hidden?
3. Which event or state transition wakes the feature?
4. What exact condition makes it sleep again?
5. Can updates arrive in bursts, and if so how are they coalesced?
6. Which data is canonical and which data is derived or cached?
7. Does the change add an `OnUpdate`, timer, ticker, event, hook, allocation,
   sort, or full-data scan to a hot path?
8. How will the human verify activation, normal operation, and shutdown after
   `/reload` in World of Warcraft?

If a pass cannot answer these questions, its design is not ready for approval.

## Exceptions

WoW APIs or protocol guarantees can require persistent event registration.
Such an exception is acceptable when it is event-driven, does no irrelevant
work, and is documented in the implementation plan. Convenience alone is not
an exception.

## Deferred load-on-demand work

Splitting Trends and its historical data into a separate LoadOnDemand addon is
planned for v1.1 in September. Until that project starts, performance passes
must not change the current packaging boundary as incidental cleanup.
