docs: narrow AdreMa ownership to address provider

README.md

@@ -5,9 +5,8 @@
 <!-- govoplan-repository-type:end -->
 
 `govoplan-addresses` is the reusable address and recipient-source module. It
-owns long-lived address directories and makes them available to campaigns,
+owns long-lived address directories and contact points and makes them available
-mail, forms, reporting, portal, and postbox modules through platform
+to consumers through platform capabilities.
-capabilities.
 
 The campaign module may import campaign-local recipient tables, but reusable
 address management belongs here.
@@ -54,9 +53,9 @@ deletion because Addresses cannot prove that it owns them.
 
 `govoplan-addresses` owns:
 
-- Adrema-style person, organization, household, and postal-address records
+- scoped address books, vCard-compatible contacts, and postal/email/phone
-- reusable email address lists and postal-letter recipient views
+  contact points
-- segments and reusable recipient-source definitions
+- classical address-only lists and recipient-source views
 - consent, legal-basis, and communication-preference metadata
 - deduplication, merge, and address quality workflows
 - import/export of reusable address directories
@@ -69,6 +68,8 @@ It must not own:
 - SMTP/IMAP transport
 - file storage
 - global identity authentication or RBAC evaluation
+- typed IDM groups, identity relationships, organization structures, or
+  effective function assignments
 - operational distribution lists/`Verteiler` with mixed recipient types
 
 ## First Capabilities
@@ -112,4 +113,4 @@ decision path, but consumers should not import or duplicate policy logic.
 
 - [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md)
 - [Implementation plan](docs/IMPLEMENTATION_PLAN.md)
-- [AdreMa capability assessment](docs/ADREMA_CAPABILITY_ASSESSMENT.md)
+- [AdreMa capability assessment and Distribution Lists roadmap](https://git.add-ideas.de/GovOPlaN/govoplan-dist-lists/src/branch/main/docs/ADREMA_CAPABILITY_ASSESSMENT.md)

docs/ADDRESS_MODULE_ARCHITECTURE.md

@@ -17,7 +17,7 @@ targets layered on top of the same local model and sync contracts.
 `govoplan-addresses` owns:
 
 - scoped address books
-- contacts, organizations, households, and postal/email/phone address data
+- vCard-compatible contacts and postal/email/phone contact-point data
 - vCard import/export and vCard-compatible field mapping
 - reusable recipient sources and classical address lists
 - contact tags, categories, communication preferences, consent, and legal basis
@@ -31,9 +31,12 @@ It does not own:
 - mail transport, mailbox access, or delivery queues
 - calendar events or iCalendar event storage
 - global identity authentication or authorization decisions
-- organization structure or internal function assignments
+- IDM identities, typed groups, effective-dated relationships, or identity
-- operational distribution lists/`Verteiler` with mixed users, identities,
+  lifecycle state
-  groups, functions, roles, raw recipients, and nested lists
+- organization structures, units, function definitions, or function
+  assignments
+- operational distribution lists/`Verteiler` with mixed address contacts, IDM
+  identities/groups, functions, raw targets, Dataflow rows, and nested lists
 
 ## Scopes
 
@@ -55,7 +58,8 @@ fields:
 - name components and formatted names
 - nicknames and display names
 - email addresses, phone numbers, postal addresses, URLs, notes, categories
-- organizations, titles, roles, departments, and relationships
+- organization, title, role, department, `KIND`, and `RELATED` values needed for
+  vCard round-trip compatibility
 - birthday/anniversary where allowed by policy
 - photos/avatars where storage and privacy policy allow them
 - calendar or scheduling addresses where present
@@ -180,12 +184,20 @@ stable IDs while keeping their own domain evidence. Cross-module UI must hide
 write actions when no writable target exists, or show the writer decision
 message when a disabled action remains visible for context.
 
-Operational distribution lists belong in `govoplan-dist-lists`. They may later
+Operational distribution lists and reusable dynamic segments belong in
-consume address lists as one entry type, but they own mixed recipient expansion
+`govoplan-dist-lists`. They may consume address lists as one entry type, but
-for users, identities, organization units, groups, functions, roles, raw
+they own mixed recipient expansion for address contacts, IDM identities and
-recipients, and nested lists. Workflow and Tasks own `Umlauf` execution state;
+typed groups, organization units, functions/effective incumbents, raw targets,
+Dataflow-backed rows, and nested lists. Workflow owns `Umlauf` execution state;
 distribution lists define who is included, not how work circulates.
 
+Organizations owns unit and function definitions. IDM owns effective-dated
+identity-to-function assignments and typed group relationships. Identity
+lifecycle status is not a business audience status; a selectable business
+status is represented by a group, function, or effective-dated relationship.
+Addresses may link contact points to stable provider references without copying
+those provider-owned facts.
+
 ## Deferred Work
 
 The following are valuable but not required for the first functional milestone:
@@ -193,6 +205,6 @@ The following are valuable but not required for the first functional milestone:
 - automatic deduplication and merge suggestions
 - two-way sync conflict UI
 - Microsoft/Google connectors
-- household and relationship editing
+- richer vCard `KIND`/`RELATED` round-trip and provider-reference linking
 - advanced consent-policy automation
 - contact activity timeline across all modules

docs/ADREMA_CAPABILITY_ASSESSMENT.md

@@ -1,418 +0,0 @@
-# AdreMa Capability Assessment
-
-## Purpose
-
-This document records a behavior-level assessment of the historical AdreMa
-application supplied in `/mnt/DATA/tmp.tar`. The goal is not to reproduce its
-implementation or UI. The goal is to preserve the useful administrative
-capabilities while replacing hard-coded queries and output paths with
-governed, reusable GovOPlaN contracts.
-
-The archive was inspected as untrusted historical material. No archived code
-was executed. Generated documents and record-level output were excluded from
-the analysis.
-
-## Evidence And Handling
-
-- Archive SHA-256:
-  `328edbaf05df084f9c63cc3b9b36f7c5ae0c639942be4b7ad830efc0905a311b`
-- Compressed size: about 1.49 GB
-- Inventory: 8,966 files and 190 directories
-- Uncompressed payload: about 1.79 GB
-- The AdreMa selection UI contains 258 distinct segment variables, 265 query
-  cases, 13 sort definitions, seven action definitions, and 24
-  department-specific forms.
-- The adjacent configurable list/report layer contains 47 ETI definitions.
-- The wider print-server archive contains 127 SQL files, 181 XSLT files, and 82
-  Python workflow sources.
-
-The archive contains generated person-level documents and embedded
-credentials. It must not be committed, copied into test fixtures, or treated as
-safe sample data. Any credential that could still be valid must be rotated.
-Future fixtures derived from this assessment must be synthetic.
-
-## What AdreMa Actually Is
-
-AdreMa is not primarily a master address database. It is a role-specific
-audience selection and output application over authoritative institutional
-databases.
-
-Its main flow is:
-
-1. Authenticate against a directory.
-2. Show a menu of saved recipient selections permitted for the current user or
-   department.
-3. Run a fixed SQL selection against organization, person, employment,
-   function, student, geography, and address data.
-4. Apply a selected sort order and address variant.
-5. Produce a table, spreadsheet, label preview, label file, central print job,
-   or BCC mail draft.
-6. Record a basic process log and recipient count.
-
-The broader print-server application adds SQL-to-XML extraction, XSLT
-transformation, HTML/Excel output, TeX/PDF generation, batch letters, PDF
-protection, printer selection, and direct print-queue submission.
-
-This means an AdreMa replacement should not be one large Addresses feature.
-It is a vertical composition of Addresses, Organizations/IDM, Datasources,
-Connectors, Dataflow, Distribution Lists, Templates, Campaign, Files, Audit,
-Policy, Reporting, Workflow, and a future print-delivery capability.
-
-## Observed Functional Model
-
-### Sources And Identities
-
-The application reads live authoritative data rather than maintaining a
-separate copy. Its selections use:
-
-- people and institutional units
-- functions and role assignments
-- employment and student state
-- effective dates and exclusions
-- internal and external organizations
-- geography, country, and postal-code ranges
-- source-specific person, registration, and unit identifiers
-
-Access to selections is hard-coded by user and department. Administrative
-users receive the union of those menus.
-
-### Contact And Address Semantics
-
-Observed recipient fields include:
-
-- display name, given name, family name, title, and formal salutation
-- organization/unit and function context
-- phone, fax, email, and URL
-- `care of`/`for the attention of` lines
-- street, postal code, locality, country, and internal mail routing
-- person, registration, and organizational-unit identifiers
-- address purpose variants such as private, semester, home, business, service,
-  and correspondence address
-- effective employment or membership data used to decide eligibility
-
-The legacy system also allows a requested number of labels for an individual
-recipient. That quantity belongs to an output job, not to the canonical address
-record.
-
-### Recipient Selection
-
-Selections cover several distinct patterns:
-
-- static categories of institutional units
-- people assigned to a function or organizational level
-- current-state selections with effective-date rules and exclusions
-- geographic and demographic selections
-- combinations and unions of predefined audiences
-- explicit person or unit lookup by source identifier
-- department-specific variants of a shared audience
-- user-selected additional predicates and sort orders in the adjacent ETI
-  report layer
-
-The important reusable abstraction is therefore a versioned, parameterized,
-permissioned segment definition. The 265 query branches must not become 265
-new backend endpoints.
-
-### Output
-
-The directly observed output modes are:
-
-- on-screen recipient table with contact and postal fields
-- spreadsheet export
-- plain-text label preview
-- generated label file
-- emailed label file
-- central label printing
-- BCC mail draft
-
-The adjacent print-server flows additionally produce:
-
-- formatted lists and grouped reports
-- personalized letters and notices
-- HTML, spreadsheet-compatible, TeX, PostScript, and PDF artifacts
-- printer-specific layouts and direct print jobs
-- password-protected output and combined document bundles
-
-### Configuration
-
-The ETI layer is an early configuration-driven report system. A definition can
-declare:
-
-- a SQL source
-- named optional filter predicates
-- named sort orders
-- list and label layouts
-- page, line, margin, repetition, and format settings
-- screen or spreadsheet output
-
-That is conceptually close to a GovOPlaN combination of a Dataflow template,
-typed output template, and Report/Campaign run configuration.
-
-## Legacy Limitations We Should Not Reproduce
-
-- users, departments, permissions, query variants, and output paths are
-  hard-coded
-- credentials are embedded in source files
-- request values are interpolated into SQL and shell commands
-- authentication, authorization, session transfer, and application routing are
-  coupled
-- selection names do not carry version, owner, purpose, legal basis, or
-  provenance
-- past output cannot be reproduced reliably after source data or query code
-  changes
-- exclusions and exceptional recipients are hidden inside SQL
-- there is no first-class consent, suppression, address-quality, or duplicate
-  resolution model
-- mail generation relies on client-side `mailto` BCC links
-- print operations have weak status, retry, cancellation, and evidence
-  handling
-- temporary files and generated artifacts are not governed records
-- the UI does not explain why a recipient was included, excluded, or
-  inaccessible
-
-## Current GovOPlaN Coverage
-
-| Capability | Current state | Primary owner |
-| --- | --- | --- |
-| Scoped address books and contacts | Implemented | Addresses |
-| Multiple email, phone, and postal contact points | Implemented | Addresses |
-| Static address lists | Implemented | Addresses |
-| vCard import/export and CardDAV sync | Implemented | Addresses |
-| Read-only lookup and immutable email-recipient snapshots | Implemented | Addresses |
-| Source provenance and sync conflicts | Implemented | Addresses |
-| Governed source catalogue, snapshots, and frozen states | Implemented first slice | Datasources |
-| Connector-backed tabular acquisition and preview | Implemented first slice | Connectors |
-| Graphical/SQL transformations, joins, filters, expressions, quality, and reconciliation | Implemented broad first slice | Dataflow |
-| Campaign snapshots, review, mail delivery, and evidence | Implemented for mail | Campaign/Mail |
-| Typed template library and document rendering | Scaffold/issue only | Templates |
-| BI reports and spreadsheet-grade exports | Scaffold/issue only | Reporting |
-| Mixed operational distribution lists | Contract/implementation issues only | Distribution Lists |
-| Dynamic address segments, consent, suppression, and preferences | Open issue | Addresses |
-| Deduplication, merge, quality, and complete history | Open issue | Addresses |
-| Postal recipient resolution and channel-neutral snapshots | Missing | Addresses |
-| Direct governed print jobs | Missing | Future Print module plus connector providers |
-| End-to-end guided AdreMa workflow | Missing | Workflow plus consuming modules |
-
-## Target Architecture
-
-### 1. Canonical Parties And Contact Points
-
-Addresses should model locally managed parties while linking, rather than
-duplicating, authoritative IDM and Organizations records.
-
-Required additions:
-
-- party kind: person, organization, household, group, or location
-- formal and display-name components, locale, title, and salutation
-- optional stable references to identity, organization, unit, and function
-  providers
-- typed relationships such as member, employee, office holder, household
-  member, assistant, or care-of contact
-- effective dates and provenance on relationships and contact points
-- postal fields for care-of/addressee lines, PO boxes, country codes, internal
-  mail routes, and delivery instructions
-- purpose and preference metadata for private, business, service,
-  correspondence, billing, and other address uses
-
-The model must remain usable when IDM or Organizations is absent. Optional
-provider links enrich a local party; they do not make those modules hard
-dependencies.
-
-### 2. Governed Segments
-
-Addresses owns the address-domain segment definition and user experience.
-Dataflow evaluates complex tabular predicates, while Datasources and Connectors
-provide governed inputs.
-
-A segment needs:
-
-- immutable definition revisions
-- system, tenant, group, and user scope
-- complete-flow versus reusable-template semantics
-- parameters with types, defaults, constraints, and permitted overrides
-- explicit include, exclude, and manual-override sets
-- source fingerprints and freshness requirements
-- preview, count, sample, and "why included/excluded" diagnostics
-- schedule/event refresh policy where materialization is wanted
-- owner, purpose, legal basis, retention, and policy provenance
-- materialized/frozen recipient snapshots for reproducible use
-
-Simple tag/contact filters can execute in Addresses. Cross-source joins and
-complex expressions should compile to a Dataflow revision rather than creating
-a second query engine.
-
-### 3. Recipient Resolution
-
-The current recipient-source DTO is email-oriented. AdreMa parity needs a
-versioned channel-neutral contract that can resolve:
-
-- email targets
-- postal targets
-- internal-mail targets
-- postbox targets where Postbox is installed
-- unresolved or blocked targets with stable reason codes
-
-Resolution must consider:
-
-- requested channel and communication purpose
-- effective date
-- preferred address/contact point
-- explicit address-purpose selection and fallback rules
-- locale and international postal formatting
-- consent, legal basis, suppression, and policy decisions
-- duplicate targets and household/organization grouping
-- source revision, selected contact-point ID, and complete provenance
-
-Consumers freeze the resolution result. They never retain only a live pointer
-to an address list or segment.
-
-### 4. Static And Operational Lists
-
-The existing split remains correct:
-
-- Addresses owns address-only lists and address-domain segments.
-- Distribution Lists owns mixed operational `Verteiler` containing address
-  records, identities, users, groups, organization units, functions, roles,
-  raw targets, and nested distribution lists.
-- Workflow/Tasks owns an `Umlauf` with ordering, state, deadlines, escalation,
-  and decisions.
-
-Distribution-list entries need stable IDs. A consumer stores an immutable
-expansion snapshot. Consumer-specific enrichment belongs to that consumer;
-reusable derived lists are separate, revision-pinned definitions.
-
-### 5. Templates, Artifacts, And Delivery
-
-Templates should provide typed render contracts for:
-
-- labels and label sheets
-- envelopes
-- form and serial letters
-- email and postbox messages
-- list/report layouts
-
-Templates declare required fields and output capabilities. Rendering produces a
-managed Files artifact with template revision, input snapshot hash, renderer
-version, page/count summary, and diagnostics.
-
-Campaign should orchestrate postal batches in the same way it orchestrates
-mail: freeze recipients, validate required fields, review exceptions, render,
-approve, deliver or export, reconcile outcomes, and retain evidence.
-
-Direct physical printing deserves a dedicated domain boundary once implemented:
-
-- Print owns printers, queues, jobs, status, cancellation, retry, accounting,
-  secure release, and job evidence.
-- Connectors supplies IPP/CUPS, Windows print-server, or provider-specific
-  connection profiles.
-- Campaign, Templates, Files, and Workflow consume a versioned print capability.
-
-Downloading a generated PDF is a valid deployment without Print installed.
-Matching AdreMa's direct central-print behavior requires Print.
-
-### 6. Governance And Quality
-
-Parity is not sufficient without:
-
-- purpose- and channel-specific consent/legal-basis records
-- do-not-contact and returned/invalid-address suppression
-- normalization and validation with original-value preservation
-- duplicate candidates, survivorship rules, manual merge/split, and undo
-  evidence
-- field-level provenance and source-of-truth precedence
-- stale-source and stale-segment warnings
-- field/row/export policy decisions with user-readable explanations
-- complete audit events for read, export, resolution, merge, rendering, and
-  delivery
-- retention, legal hold, and deletion behavior for source records and frozen
-  output evidence
-
-### 7. Guided User Experience
-
-The default journey should be:
-
-1. Choose or create an address list/segment.
-2. Preview the authorized audience and inspect included, excluded, duplicate,
-   invalid, and suppressed counts.
-3. Select channel, address purpose/fallback, sort, and grouping.
-4. Freeze a recipient snapshot.
-5. Select a compatible template/output format.
-6. Review individual exceptions and approve the run.
-7. export, send, or print through available capabilities.
-8. inspect progress, outcomes, returned items, and evidence.
-
-Workflow may package this as a reusable guided process and activate a focused
-View. Every underlying resource must remain independently accessible and
-permission-checked.
-
-## Representative Golden Flow
-
-Before migrating any historical selection, build a synthetic AdreMa fixture
-covering:
-
-- people, organizations, units, functions, and effective-dated assignments
-- multiple postal-purpose variants and internal mail
-- a function-based segment
-- an organization-unit segment
-- a geography-based segment
-- a union of segments
-- explicit inclusion and exclusion
-- duplicate and suppressed recipients
-- deterministic sorting and address fallback
-- frozen postal and email snapshots
-- label, spreadsheet, and letter output expectations
-
-The fixture should assert exact recipient IDs, selected contact-point IDs,
-ordering, exclusion reasons, source fingerprints, and output hashes. It must
-contain no archived record-level data.
-
-## Migration Strategy
-
-Do not translate the legacy source one query branch at a time into application
-code.
-
-1. Inventory each still-relevant named selection with owner, purpose, legal
-   basis, source systems, parameters, output type, and expected use frequency.
-2. Retire obsolete and duplicate selections before migration.
-3. Map source tables to governed Connector/Datasource definitions.
-4. Convert reusable predicates into Dataflow templates or simple
-   Addresses-owned filters.
-5. compare the new result against an authorized legacy run using counts and
-   pseudonymized stable keys.
-6. approve and version the new segment.
-7. migrate output layouts into typed Templates.
-8. retain a migration report and decommission the corresponding legacy path.
-
-## Recommended Delivery Order
-
-### Priority 1: Functional Parity Foundation
-
-1. Typed party, relationship, address-purpose, and effective-date model.
-2. Channel-neutral recipient resolution with postal snapshots.
-3. Dynamic governed segments through Dataflow/Datasources.
-4. Synthetic AdreMa golden-flow fixture.
-5. Typed label, envelope, and letter templates with managed artifacts.
-
-### Priority 2: Operational Parity
-
-1. Campaign postal-batch review and output flow.
-2. Spreadsheet/report exports with exact frozen-snapshot evidence.
-3. Consent, suppression, preferences, deduplication, merge, and quality UI.
-4. CSV/XLSX and directory/database migration profiles.
-5. Distribution-list expansion and Campaign integration.
-
-### Priority 3: Beyond AdreMa
-
-1. Direct governed print jobs and secure release.
-2. returned-mail and correction workflows.
-3. postal-provider/franking integration and delivery reconciliation.
-4. scheduled/event-driven segment refresh and recurring campaigns.
-5. address analytics, geocoding where policy permits, and quality trends.
-
-## Completion Standard For The Umbrella Feature
-
-The AdreMa umbrella is complete when a user can define or reuse a permissioned
-audience, explain and freeze the exact recipients, create reviewed label/letter
-or digital outputs, send/export/print through installed modules, and later
-prove exactly which source data, rules, template, actor, and delivery outcome
-were involved. The same flow must degrade cleanly when optional modules such as
-Mail, Campaign, Templates, Workflow, Reporting, or Print are absent.

docs/IMPLEMENTATION_PLAN.md

@@ -216,12 +216,13 @@ Tasks:
 - Exchange/Microsoft 365 contacts connector
 - Google Contacts connector
 - CSV/XLSX/LDIF import mapping profiles
-- classical address-list UI and static/dynamic address-domain segments
+- classical address-list UI; reusable static/dynamic operational segments move
+  to `govoplan-dist-lists`
 - operational distribution lists move to `govoplan-dist-lists`
 - consent, legal-basis, suppression, and communication preferences
 - deduplication and merge workflow
 - address quality checks and normalization
-- relationship/household/organization editing
+- richer vCard `KIND`/`RELATED` round-trip and stable links to IDM/Organizations
 
 Exit criteria: