**`docs/adr/0001-new-runtime.md`**
```md
# ADR 0001: Create a new runtime project instead of evolving the legacy ConfigManager model

## Status

Accepted

## Context

The previous generation of the application runtime was centered around a timer-driven execution model:
- a manager loaded configuration
- a worker loop periodically called `execute()`
- applications placed most operational logic behind that entry point

That model is adequate for simple periodic jobs, but it does not match the direction of the new platform.

The new platform must support:
- task sources
- queue-driven processing
- multiple parallel workers
- trace propagation across producer/consumer boundaries
- richer lifecycle and status management
- health aggregation
- future admin web interface
- future authentication and user management

These are platform concerns, not business concerns.

We also want business applications to describe only business functionality and rely on the runtime for infrastructure behavior.

## Decision

We will create a new runtime project instead of implementing a `V3` directly inside the current legacy ConfigManager codebase.

The new runtime will be built around a platform-oriented model with explicit concepts such as:
- `RuntimeManager`
- `ApplicationModule`
- `TaskSource`
- `TaskQueue`
- `WorkerSupervisor`
- `TaskHandler`
- `TraceService`
- `HealthRegistry`

The old execute-centered model is treated as a previous-generation design and is not the architectural basis of the new runtime.

## Rationale

Creating a new runtime project gives us:
- freedom to design the correct abstractions from the start
- no pressure to preserve legacy contracts
- cleaner boundaries between platform and business logic
- simpler documentation and tests
- lower long-term complexity than mixing old and new models in one codebase

If we built this as `V3` inside the old project, we would likely inherit:
- compatibility constraints
- mixed abstractions
- transitional adapters
- conceptual confusion between periodic execution and event/queue processing

The expected long-term cost of such coupling is higher than creating a clean new runtime.

## Consequences

### Positive

- the platform can be modeled cleanly
- business applications can integrate through explicit contracts
- new runtime capabilities can be added without legacy pressure
- mail_order_bot can become the first pilot application on the new runtime

### Negative

- some existing capabilities will need to be reintroduced in the new project
- there will be a temporary period with both legacy and new runtime lines
- migration requires explicit planning

## Initial migration target

The first application on the new runtime will be `mail_order_bot`.

Initial runtime design for that application:
- IMAP polling source
- in-memory queue
- parallel workers
- business handler for email processing
- message marked as read only after successful processing

Later:
- swap IMAP polling source for IMAP IDLE source
- keep the queue and worker model unchanged

## What we intentionally do not carry over

We do not keep the old architecture as the central organizing principle:
- no `execute()`-centric application model
- no timer-loop as the main abstraction
- no implicit mixing of lifecycle and business processing

## Follow-up

Next design work should define:
- core platform contracts
- package structure
- runtime lifecycle
- queue and worker interfaces
- config model split between platform and application
- pilot integration for `mail_order_bot`