# Development

## Stack

The initial implementation uses Python 3.12 and the standard library. The
first slice intentionally avoids runtime dependencies so the repository can be
tested immediately in local and agent environments.

## Layout

```text
src/user_engine/
  adapters/    local standalone adapters and deterministic test doubles
  domain/      transport- and persistence-neutral domain schemas
  errors.py    typed service exceptions for callers and future transports
  ports.py     adapter protocols for identity, authorization, events, audit,
               membership export, application bindings, and secrets
  service.py   headless service API for the isolated MVP
  testing/     local fixtures for tests and examples
tests/         standard-library unittest suite
```

The domain layer should not import HTTP frameworks, database clients, or
platform-specific SDKs. Those integrations belong behind ports.

## Commands

```bash
make test
```

The command runs:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'
```

## Implementation Rule

Add new behavior in this order:

1. domain schema or port;
2. local fixture or adapter;
3. test that proves the boundary;
4. infrastructure adapter or API surface.

## Isolated MVP Surface

The initial headless API is `UserEngineService`. It exposes health,
readiness, `me`, user/account lifecycle, identity linking, application
registration, catalog publication, profile writes, effective profile
resolution, projections, audit inspection, and outbox inspection. The first
store is `InMemoryUserEngineStore`, which carries an explicit schema version
and migration hook so later database-backed stores have a contract to match.

## Tenant Surface

Tenant-aware operations resolve an explicit `TenantContext` before mutating
tenant-scoped state. Tenant admins can operate inside their own tenant, while
platform-root and cross-tenant operations require the `platform-operator`
role. Tenant account state, memberships, tenant profile layers, authorization
facts, audit records, outbox events, and diagnostics all carry the resolved
tenant.