# 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
- purpose-aware Addresses contact-point resolution for email and postal targets
- snapshot DTOs with exact rendered targets, contact-point IDs, source revision,
  fingerprint, and decision 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.
When the optional `idm.relationships` capability is present, `idm_group`
entries resolve at the requested effective time. Included and excluded links
retain stable decision codes, relationship revisions, external source
references, and provenance in previews and frozen snapshots. If IDM is absent,
the entry is reported as unavailable without affecting other entry types.

## 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
```

Campaign consumes the optional `dist_lists.source` and `dist_lists.expand`
capabilities. Its Recipient data surface can enter list parameters, preview all
decisions, freeze a snapshot, and deliberately refresh when the list revision
drifts. The Campaign copy retains list/revision/entry/provider/channel evidence;
Campaign enrichment and review never write back to the reusable list.

## 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)

## Git-source WebUI package

The repository root exposes `@govoplan/dist-lists-webui` for Git-tagged release
dependencies. It mirrors the owning `webui/package.json` version, public
TypeScript/CSS exports and peer requirements, with entry paths under
`webui/src`. Consumers provide the shared Core/React peers; the facade runs no
development or install scripts. The source archive contains `webui/src`, this
README and any repository license file. Run module development checks from `webui/`; Python
installation remains governed by `pyproject.toml`.

Das Repository stellt `@govoplan/dist-lists-webui` am Wurzelpfad für versionierte
Git-Abhängigkeiten bereit. Version, öffentliche TypeScript-/CSS-Exporte und
Peer-Anforderungen entsprechen `webui/package.json`; die Einstiegspfade liegen
unter `webui/src`. Gemeinsame Core-/React-Peers stellt die einbindende Anwendung
bereit. Die Fassade führt keine Entwicklungs- oder Installationsskripte aus.
Entwicklungsprüfungen bleiben in `webui/`, die Python-Installation weiterhin in
`pyproject.toml` definiert.