# PLBA v2 PLBA v2 is a transport-neutral Python library for application lifecycle, workers, health aggregation, configuration snapshots, workflows, business tracing, and structured technical logs. It is a separate package from PLBA v1. The application owns its entrypoint and composition root, business logic, HTTP host and listener, database schema and migrations, and message queues. PLBA2 provides components and adapters that the application wires together; it does not start a service or create a second HTTP port. ## Capabilities - `runtime/application-identity` resolves `application_id` from `config.yaml`, then `[project].name` in `pyproject.toml`, then UUIDv4. - `runtime/worker` registers uniquely named workers, applies the `disabled` flag, runs sequential scheduled cycles, combines application and automatic health, and supports graceful or force stop. - `runtime/application-lifecycle` starts and stops all enabled workers and reports application lifecycle states. - `health/aggregation` combines worker and contributor states, criticality, missing components, and application lifecycle into a health report. - `api/http/control-api` is a mountable ASGI adapter for `GET /health`, `POST /runtime/start`, `POST /runtime/stop`, and `GET /runtime/status`. - `configuration/application-config-file` loads an application-typed root `config.yaml` and atomically reloads valid snapshots without a restart. - `configuration/application-settings` provides a typed `SettingsReader` and a PostgreSQL adapter for the application's `settings` table. - `workflow/orchestration` executes named object-based steps through declared transitions and persists run and step snapshots through an application port. - `observability/business-tracing` provides trace contracts and a PostgreSQL writer for application-owned `trace_contexts` and `trace_messages` tables. - `observability/technical-logging` formats JSON log records with application and business trace identifiers for stdout. ## Install ```bash pip install . ``` The PostgreSQL adapters accept the application's pool and schema. PLBA2 does not install or manage a database driver. The HTTP adapter uses ASGI and does not install or manage an HTTP server. ## Composition outline The application loads and validates configuration before building dependent components. It supplies a decoder for its own typed fields: ```python config_loader = ApplicationConfigLoader( Path("config.yaml"), application_decoder=ServiceConfig.from_mapping ) config_manager = ApplicationConfigManager(config_loader) initial_config = config_manager.load_initial() identity = ApplicationIdentityResolver( TomlProjectNameReader(Path("pyproject.toml")) ) runtime_context = identity.resolve(initial_config.application_id) workers = WorkerRegistry() workers.register(WorkerDefinition("inventory_sync", sync_inventory)) supervisor = WorkerSupervisor(workers, config_manager) runtime = ApplicationRuntime(runtime_context, supervisor) ``` The application creates its HTTP host and mounts `ControlApi` on the same listener. `RuntimeHealthInputProvider` connects the runtime, worker supervisor, and registered health contributors to `HealthAggregator`. The application starts its own server and chooses when to call `runtime.start()` and `runtime.stop()`. For configuration changes, run `config_manager.watch(...)` in an application task and handle reload errors in the supplied callback. Existing snapshots remain stable; an invalid update leaves the latest valid snapshot active. ## Database ownership The application creates and seeds `settings` in its migrations. It also creates `trace_contexts` and `trace_messages` in its migrations. PLBA2 does not create tables, run application migrations, copy YAML into the database, expose a business-history API, publish business events to RabbitMQ, or provide shared worker-message queues. See [database contracts](docs/database-contracts.md) and [configuration](docs/configuration.md) for the consumer-facing contracts. See [integration guidance](docs/integration.md) for wiring the HTTP, database, workflow, trace, and logging adapters into an application. ## Development ```bash python3 -m pytest ```