# PLBA Requirements

## Goal

`PLBA` is a reusable runtime for business applications.

The platform owns:
- lifecycle
- worker orchestration
- configuration loading
- logging configuration
- health aggregation
- tracing
- control endpoints

Business applications own:
- business workflows
- domain services
- app-specific configuration schema
- business error semantics

## Core runtime model

The platform is built around workers.

1. application defines an `ApplicationModule`
2. module registers workers
3. runtime starts workers
4. workers execute business activity
5. runtime aggregates status and health
6. runtime stops workers gracefully

## Contracts

### `ApplicationModule`

Responsibilities:
- provide module name
- assemble application components
- register workers
- register optional health contributors

### `Worker`

Main runtime contract.

Responsibilities:
- `start()`
- `stop(force=False)`
- `health()`
- `status()`

The worker owns execution mechanics:
- single-run or loop
- thread model
- stop conditions
- runtime status
- health interpretation

### `Routine`

`Routine` is an application pattern, not a PLBA contract.

Responsibilities:
- execute business behavior
- call domain services
- apply business rules
- talk to external integrations

Recommended rule:
- worker orchestrates
- routine executes business behavior

## Architectural rules

### 1. Keep lifecycle and business behavior separate

Good:
- worker manages threading, loop, stop flags, health, status
- routine contains business logic

Bad:
- worker mixes thread management, retry policy, parsing, persistence, integration rules, and domain decisions in one class

### 2. Treat `Worker` as the main extension point

Do not center the platform around queues, handlers, sources, or other specialized runtime categories.

### 3. Keep `Routine` out of the platform contract set

At the current stage PLBA should not force a universal `Routine` interface.

Applications may use:
- `run()`
- `run_once()`
- `poll()`
- `sync_window()`

The exact business API belongs to the application.

### 4. Health is computed by the worker

Routine should not directly mutate platform health state.

Instead:
- routine succeeds
- routine returns outcome
- or routine raises typed exceptions

Worker interprets the outcome into:
- `ok`
- `degraded`
- `unhealthy`

### 5. `InMemoryTaskQueue` is utility-only

`InMemoryTaskQueue` may stay as a reusable component for business applications.

It is:
- optional
- local
- not part of the main runtime contract model

## Public package direction

Public namespace `plba` should expose:
- application/runtime contracts
- tracing
- health
- config
- control plane
- utility queue

It should not expose queue-centric runtime abstractions as primary architecture.