# Themelio Python scaffolding

Themelio is an independently packaged Python service with no bounded contexts.
`contexts/` contains only its package initialiser. Its production composition opens
no databases, starts no delivery workers and registers no business routes,
commands, queries, events, subscriptions or browser projections.
Its empty event, subscription and service-lifecycle manifests generate the same
installed-or-pending runtime registry used by Metallo, ready for the first owner.

The technical foundation follows the Operations service at reference commit
`a9d7bf6`, plus the reply-routing and authenticated-actor changes in `ea88398`,
in `ddd-hexagonal-cqrs-es-eda-microservices-multilingual` (16 October 2026).
It adopts Dependency Injector composition, direct command registration, named read
and write repository ports, transactional command execution, durable private
commands, separate domain-event publication, explicit realtime publication and
schema-generated plain shared request/response types. Reference business contexts
and their contracts are excluded.

## Layout

| Directory | Responsibility |
| --- | --- |
| `foundation/` | Plain domain values, application ports, command metadata and repository interfaces |
| `adaptors/persistence/` | PostgreSQL transactions, receipts, immutable outgoing bytes and fenced leases |
| `adaptors/messaging/` | Typed envelopes, command/query dispatch, confirmed RabbitMQ delivery and retries |
| `adaptors/realtime/` | Explicit typed projections and scoped gateway publication |
| `adaptors/http/` | Operational authentication and redacted errors |
| `contracts/` | Service-local technical schemas, generated plain values and delivery baseline |
| `services/` | Dependency Injector composition, worker lifecycle and replay entry point |
| `contexts/` | Empty; future owner models belong here |
| `tests/` | Technical fixtures, deterministic checks and explicit infrastructure lanes |

Pharos retains direct service-local packages and `services/` composition roots.
Both editable installations and wheels expose one `themelio` package. Imports
never reach into Metallo or another service. The existing Pharos Protobuf envelopes,
`pharos` database schema, broker names and scoped realtime gateway remain in use.

## Run and check

From the repository root:

```sh
uv sync --project services/themelio --frozen
APP_ENV=development API_KEY_FILE=/path/to/private/service-key \
  uv run --project services/themelio --frozen uvicorn \
  themelio.services.service:create_app --factory --host 127.0.0.1 --port 8080
pnpm generate:contracts
pnpm verify
pnpm test:integration
```

The development service key must contain at least 32 characters. `/healthz` is
public for Kubernetes probes; `/diagnostics` requires its bearer key and returns
`Cache-Control: no-store`. OpenAPI and interactive API documentation are disabled.
Native and Docker takeover use the same Python factory with source reload.

The integration harness gives Themelio its own logical database and restricted
credentials on the same disposable PostgreSQL instance. Service-local migrations
`0003_delivery.sql` and `0004_reply_routes.sql` add immutable private commands,
exact command replies with connection-specific destinations and explicit browser
outcomes to the frozen shared baseline. Administrator migration tooling applies
the same checksummed extensions to future
Themelio context databases. Runtime code verifies its schema and has no DDL grants.
Other services retain their own baseline. No platform context is enrolled here.

Command metadata carries the authenticated actor into the plain handler context
and receipt fingerprint. Blank actors preserve legacy/internal compatibility.
Reply addresses are owner-scoped and validated before dispatch; persisted replies
retain their original destination across recovery.

## First context

Follow the repository's [context checklist](../../docs/adding-a-context.md).
The current API contract generation and runtime broker provisioning remain
Project-specific. The next context must generalise that tooling and declare its
own authority; the empty Themelio scaffold does not provision business queues.
Extend `scripts/generate_themelio.py` with owner schemas and typed registrations
before adding Themelio to `contracts/contexts.json`; the empty generator refuses
populated ownership so it cannot erase future registrations. Shared scalar models
and encoders are derived from Protobuf descriptors by
`scripts/generate_themelio_models.py`.

Declare each future event consumer in `contracts/subscriptions.json` and classify
it once in `services/subscriptions.json`. An installed entry names the process
whose composition supplies its handler. A pending entry names its tracking issue
and starts no worker. Generation rejects missing, repeated, foreign or private
cross-owner bindings.

Add one owner container beneath `services/composition`, resolve its complete graph,
and return its database and cooperative workers from the composition registry.
Feature handlers receive plain ports. The command executor owns their transaction;
event handlers persist command intent before acknowledging delivery. Aggregate
saves stage private events, and publication subscriptions map those facts into
integration events. Worker shutdown drains in-flight work before closing pools.

Add owner migrations, contracts, codecs, request factories, API bindings, broker
permissions, topology and tests together. Browser delivery additionally requires
an explicitly registered typed projection, an explicit Project, Party or principal
target and server-authorised subscription.
The empty registries reject unknown payloads. Technical test fixtures grant no
production authority.