Metadata-Version: 2.4
Name: service-foundation
Version: 2026.9.22.2029
Summary: Generic polling, retry, stop, health, and discovery lifecycle for host-side relay adapters.
Author: Elena Viter
License: MIT
Project-URL: Homepage, https://github.com/elenaviter/app-ecosystem
Project-URL: Repository, https://github.com/elenaviter/app-ecosystem
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: pytest-asyncio<2,>=0.23; extra == "test"

# service-foundation

Foundations for standalone runnable services and host-side companion
processes.

## Current Status

`2026.09.22.2029` is the first implementation candidate. It includes a generic
host-relay lifecycle under `service_foundation.host_relay`:

- `HostRelayAdapter` defines one asynchronous `poll_once()` domain boundary;
- `HostRelayRuntime` owns repeated execution, health, stop, and bounded retry;
- `HostRelayPolicy` defines poll and retry timing;
- an adapter may return `next_poll_seconds` and implement
  `wait_for_wakeup(timeout_seconds, stop_event)` so a live transport can start
  the next reconciliation cycle immediately;
- entry-point discovery uses `service_foundation.host_relay.adapters` for
  separately packaged adapters.

```bash
python -m pip install service-foundation
```

An adapter owns domain translation and returns bounded cycle metadata. The
runtime emits lifecycle metadata and result-key names; it does not copy domain
payloads into observer events.

## Boundary

A standalone service needs a host layer around its application logic:

- composition and launcher contracts;
- browser-session and service-workload authentication surfaces;
- service-owned session issuance and verification;
- configuration, health, and readiness contracts;
- migration invocation, while the application owns its migrations;
- lifecycle for a local or remote companion process.

The host-relay runtime does not know MCP, Data Bus, credentials, agents, mail,
journals, or any product vocabulary. A product composition root supplies an
adapter, opens whatever governed transport that adapter needs, and translates
transport events into wakeups. Poll timing remains reconciliation policy even
when ordinary work is push-driven.

`service-foundation` does not import `app-foundation`, and `app-foundation`
does not import `service-foundation`. Products may depend on either or both.

License: MIT. Source: https://github.com/elenaviter/app-ecosystem
