# GovOPlaN Distribution Lists

<!-- govoplan-repository-type:start -->
**Repository type:** module (domain).
<!-- govoplan-repository-type:end -->

`govoplan-dist-lists` owns reusable operational distribution lists
(`Verteiler`) for GovOPlaN. It is the core target for AdreMa-style audience
selection: definitions can resolve contacts, raw addresses, IDM identities and
typed groups, organization units, effective function incumbents,
Dataflow-backed rows, and nested lists into immutable recipient snapshots.

Classical address lists remain in `govoplan-addresses`. Distribution Lists owns
mixed operational and dynamic audiences, while Campaign, Reporting, and
Workflow consume the frozen results for delivery, analysis, and guided work.

## Boundary

Distribution Lists owns:

- reusable mixed recipient definitions
- German-administration `Verteiler` semantics
- static, parameterized, and Dataflow-backed dynamic audience definitions
- expansion of mixed entries into concrete delivery/recipient targets
- snapshot DTOs with source revision and provenance
- stale-source detection for expanded entries
- eligibility and policy explanations for disabled recipient entries
- audit evidence for who was resolved at execution time

Distribution Lists does not own:

- contacts, vCard/CardDAV address books, or address-only lists; those belong in
  `govoplan-addresses`
- identities, typed groups, effective relationships, organization units, or
  function definitions; those belong in IDM and Organizations
- delivery transports, queues, or mailbox access; those belong to consuming
  delivery modules
- campaign versions, message rendering, or delivery evidence; those belong in
  `govoplan-campaign`
- workflow/Umlauf execution state, ordering, deadlines, escalation, or task
  state; those belong in `govoplan-workflow` and `govoplan-tasks`
- global identity, organization, tenancy, access, or policy engines

IDM identity status is a lifecycle indicator. Business states used for
audience selection are typed groups, functions, or effective-dated
relationships and must not be encoded by overloading identity lifecycle state.

## Key Distinction

```text
AddressBook -> contacts and contact points
AddressList -> address-domain grouping of contacts/contact methods
DistributionList -> operational Verteiler with mixed recipient entry types
Umlauf -> workflow execution over recipients, actors, tasks, and deadlines
CampaignVersion/Report/WorkflowRun -> immutable snapshot of expanded recipients
```

## Development Install

```bash
cd /mnt/DATA/git/govoplan
./.venv/bin/python -m pip install -e ../govoplan-dist-lists
```

Focused manifest verification:

```bash
cd /mnt/DATA/git/govoplan-dist-lists
PYTHONPATH=src:/mnt/DATA/git/govoplan-core/src /mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
```

## Design Documents

- [Distribution lists architecture](docs/DISTRIBUTION_LISTS_ARCHITECTURE.md)
- [Implementation plan](docs/IMPLEMENTATION_PLAN.md)
- [AdreMa capability assessment](docs/ADREMA_CAPABILITY_ASSESSMENT.md)