Release v0.1.8

.dockerignore

@@ -0,0 +1,28 @@
+.git
+.venv
+node_modules
+webui/node_modules
+audit-reports
+runtime
+dist
+build
+coverage
+htmlcov
+__pycache__
+*.pyc
+*.pyo
+*.log
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.cache
+.component-test-build
+.module-test-build
+.policy-test-build
+.template-preview-test-build
+.import-test-build
+webui/.component-test-build
+webui/.module-test-build
+webui/.policy-test-build
+webui/.template-preview-test-build
+webui/.import-test-build

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: "Bug"
+about: "Report a reproducible defect, regression, or incorrect behavior"
+title: "[Bug] "
+labels:
+  - type/bug
+  - status/triage
+  - module/core
+---
+
+## Scope
+
+- Repository:
+- Area/module:
+- Affected version or commit:
+
+## Behavior
+
+Expected:
+
+Actual:
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Evidence
+
+Logs, screenshots, traces, or failing test output:
+
+## Verification Target
+
+Command or workflow that should pass when fixed:

.gitea/ISSUE_TEMPLATE/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.gitea/ISSUE_TEMPLATE/docs_workflow.md

@@ -0,0 +1,27 @@
+---
+name: "Docs / workflow"
+about: "Request documentation, process, or developer workflow changes"
+title: "[Docs] "
+labels:
+  - type/docs
+  - status/triage
+  - module/core
+  - area/docs
+---
+
+## Scope
+
+- Repository:
+- Document or workflow:
+
+## Current State
+
+What is missing, unclear, duplicated, or stale?
+
+## Desired State
+
+What should the docs or workflow make clear?
+
+## Verification Target
+
+How should this be checked?

.gitea/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: "Feature"
+about: "Propose new user-visible behavior or platform capability"
+title: "[Feature] "
+labels:
+  - type/feature
+  - status/triage
+  - module/core
+---
+
+## Problem
+
+What user, operator, or developer problem should this solve?
+
+## Proposed Capability
+
+What should exist when this is done?
+
+## Ownership
+
+- Owning repository:
+- Related module repositories:
+- Extension point or integration boundary:
+
+## Acceptance Criteria
+
+- [ ]
+- [ ]
+
+## Verification Target
+
+Command, scenario, or UI flow that should prove completion:

.gitea/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,28 @@
+---
+name: "Task"
+about: "Track implementation, maintenance, or migration work"
+title: "[Task] "
+labels:
+  - type/task
+  - status/triage
+  - module/core
+---
+
+## Objective
+
+What needs to be completed?
+
+## Scope
+
+- Owning repository:
+- In-scope:
+- Out-of-scope:
+
+## Checklist
+
+- [ ]
+- [ ]
+
+## Verification Target
+
+Command or manual check:

.gitea/ISSUE_TEMPLATE/tech_debt.md

@@ -0,0 +1,25 @@
+---
+name: "Tech debt"
+about: "Track cleanup, refactoring, risk reduction, or deferred engineering work"
+title: "[Debt] "
+labels:
+  - type/debt
+  - status/triage
+  - module/core
+---
+
+## Current Cost
+
+What does this make harder, riskier, slower, or more fragile?
+
+## Desired Shape
+
+What should the code, tests, or architecture look like afterwards?
+
+## Constraints
+
+What behavior, compatibility, or module boundary must be preserved?
+
+## Verification Target
+
+Focused checks that should pass:

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Issue
+
+Closes #
+
+## Summary
+
+-
+
+## Verification
+
+-
+
+## Notes
+
+Follow-up issues:

.gitignore

@@ -136,6 +136,21 @@ dist
 .yarn/install-state.gz
 .pnp.*
 
+# Local WebUI test/build scratch directories
+.component-test-build/
+.module-test-build/
+.policy-test-build/
+.template-preview-test-build/
+.import-test-build/
+webui/.component-test-build/
+webui/.module-test-build/
+webui/.policy-test-build/
+webui/.template-preview-test-build/
+webui/.import-test-build/
+
+# Security audit reports
+audit-reports/
+
 # ---> Python
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -326,3 +341,11 @@ cython_debug/
 # Built Visual Studio Code Extensions
 *.vsix
 
+*.db
+
+# GovOPlaN local runtime state
+runtime/
+
+# GovOPlaN WebUI test output
+webui/.module-test-build/
+webui/.component-test-build/

AGENTS.md

@@ -0,0 +1,50 @@
+# GovOPlaN Codex Guide
+
+## Scope
+
+This repository is the platform runner and shared core for GovOPlaN. It owns the server entry point, database/session primitives, auth, tenancy, RBAC, governance, module discovery, migrations, shared WebUI shell, and generic WebUI components.
+
+Sibling module repositories usually used with this repo:
+
+- `/mnt/DATA/git/govoplan-access`
+- `/mnt/DATA/git/govoplan-files`
+- `/mnt/DATA/git/govoplan-mail`
+- `/mnt/DATA/git/govoplan-campaign`
+
+Keep module-specific behavior in the owning module. Core may expose stable extension points, capabilities, and shared components, but should not directly import module WebUI pages or require optional module packages for core-only startup.
+
+## Local Commands
+
+Use targeted commands first:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver --smoke --no-reload
+/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_module_system
+/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_api_smoke.ApiSmokeTests.test_mailbox_message_listing_reports_total_count
+```
+
+For WebUI checks:
+
+```bash
+cd /mnt/DATA/git/govoplan-core/webui
+PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run test:mail-components
+PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run test:module-capabilities
+PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run test:module-permutations
+```
+
+Run the consolidated focused check when a change touches module discovery, optional integrations, shared mail components, or mailbox listing:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/checks/check-focused.sh
+```
+
+## Working Rules
+
+- Prefer `rg`, `sed`, and targeted tests over broad recursive scans or full builds.
+- Avoid DataGrid changes unless explicitly requested; it is intentionally brittle and has known deferred work.
+- Do not add module-to-module imports for optional integrations. Use core registry/capability/module metadata paths.
+- Treat Gitea issues as the canonical backlog and state log. Treat Gitea wiki pages as durable project context mirrored from repository and product docs. Use `docs/GITEA_ISSUES.md` for labels, templates, TODO import, wiki sync, and Codex issue updates.
+- Do not keep generated WebUI test folders in git status; they should be ignored and removable.
+- Do not start persistent dev servers unless the user asks.

README.md

@@ -1,6 +1,17 @@
 # govoplan-core
 
-GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, tenant and RBAC infrastructure, governance policy, audit/auth helpers, module discovery, migration registration, and the shared WebUI shell. Feature code is supplied by installed modules.
+<!-- govoplan-repository-type:start -->
+**Repository type:** system (kernel).
+<!-- govoplan-repository-type:end -->
+
+[![Module Matrix](https://git.add-ideas.de/add-ideas/govoplan/actions/workflows/module-matrix.yml/badge.svg?branch=main)](https://git.add-ideas.de/add-ideas/govoplan/actions?workflow=module-matrix.yml&actor=0&status=0)
+[![Release Integration](https://git.add-ideas.de/add-ideas/govoplan/actions/workflows/release-integration.yml/badge.svg?branch=main)](https://git.add-ideas.de/add-ideas/govoplan/actions?workflow=release-integration.yml&actor=0&status=0)
+[![Dependency Audit](https://git.add-ideas.de/add-ideas/govoplan/actions/workflows/dependency-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/add-ideas/govoplan/actions?workflow=dependency-audit.yml&actor=0&status=0)
+[![Security Audit](https://git.add-ideas.de/add-ideas/govoplan/actions/workflows/security-audit.yml/badge.svg?branch=main)](https://git.add-ideas.de/add-ideas/govoplan/actions?workflow=security-audit.yml&actor=0&status=0)
+
+# govoplan-core
+
+GovOPlaN core is the platform runner and shared foundation. It owns the server entry point, database/session primitives, module discovery, migration orchestration, capability contracts, install/uninstall orchestration, and the shared WebUI shell. Platform and feature behavior is supplied by installed modules.
 
 ## Repository ownership
 
@@ -9,46 +20,116 @@ Core owns:
 - `govoplan_core.server.app:app`, the FastAPI entry point used by uvicorn
 - `GovoplanServerConfig`, module discovery, registry validation, and route aggregation
 - SQLAlchemy base/session helpers and module migration registration
-- tenant/account/session/RBAC/governance/audit models and services
-- core API routes for auth, admin, platform metadata, audit, and system health
+- kernel APIs for platform metadata, module lifecycle, health, and development diagnostics
 - `@govoplan/core-webui`, including login, CSRF/API helpers, shell layout, generic UI components, IconRail, DataGrid, access boundaries, and module route/nav contracts
 
-Feature modules own their backend routers, models, migrations, permissions, frontend packages, nav items, and route contributions. Core should not import feature pages directly; it imports module manifests and renders their route contributions.
+Platform and feature modules own their backend routers, models, migrations,
+permissions, frontend packages, nav items, and route contributions. Access,
+tenancy, policy, audit, and admin behavior live in their owning platform
+modules. Core should not import feature pages directly; it imports module
+manifests and renders their route contributions.
 
 ## Governance docs
 
 Canonical policy documents live in `docs/`:
 
-- [RBAC_MANIFEST.md](docs/RBAC_MANIFEST.md)
-- [SYSTEM_GOVERNANCE_MANIFEST.md](docs/SYSTEM_GOVERNANCE_MANIFEST.md)
+- [DOCUMENTATION_MAP.md](docs/DOCUMENTATION_MAP.md)
+- [ACCESS_RBAC_MODEL.md](docs/ACCESS_RBAC_MODEL.md)
+- [GOVERNANCE_MODEL.md](docs/GOVERNANCE_MODEL.md)
 - [MODULE_ARCHITECTURE.md](docs/MODULE_ARCHITECTURE.md)
+- [DEPLOYMENT_OPERATOR_GUIDE.md](docs/DEPLOYMENT_OPERATOR_GUIDE.md)
+- [CODEX_WORKFLOW.md](docs/CODEX_WORKFLOW.md)
 
-Modules may define module-specific permissions and policy behavior, but the platform-level permission model and governance hierarchy belong here.
+Modules define module-specific permissions and policy behavior. Shared DTOs and
+composition rules live in core only where they are stable kernel contracts.
 
 ## Backend development
 
-Create or activate the core virtual environment, then install core and sibling modules from this repository:
+For whole-product development, create the virtualenv from the meta repository:
 
 ```bash
-cd /mnt/DATA/git/govoplan-core
+cd /mnt/DATA/git/govoplan
+python3 -m venv .venv
+./.venv/bin/python -m pip install --upgrade pip
 ./.venv/bin/python -m pip install -r requirements-dev.txt
 ```
 
-Run the platform server from core through the module-aware development runner. The default config loads the access/core module only; product configs can enable installed modules.
+Run the platform server from core through the module-aware development runner. The default config reads `ENABLED_MODULES` and discovers installed module entry points. Local development defaults to `tenancy,organizations,identity,access,admin,dashboard,policy,audit,campaigns,files,mail,calendar,docs,ops`; set `ENABLED_MODULES` explicitly when testing a smaller module permutation.
 
 ```bash
 cd /mnt/DATA/git/govoplan-core
-./.venv/bin/python -m govoplan_core.devserver \
-  --config app.govoplan_config:get_server_config \
+/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver \
+  --host 127.0.0.1 \
+  --port 8000
+```
+
+For example, to test campaign without files or mail:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+ENABLED_MODULES=access,campaigns /mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver \
   --host 127.0.0.1 \
   --port 8000
 ```
 
 The runner loads the same `GovoplanServerConfig` as `govoplan_core.server.app:app`, builds the platform registry, and passes core plus enabled module source roots to uvicorn as reload directories. After reinstalling the editable package, the same command is also available as `govoplan-devserver`.
 
+The default development database is PostgreSQL at `postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev`. Store the password in `~/.pgpass`. To force the disposable SQLite fallback, run with `GOVOPLAN_DEV_DATABASE_BACKEND=sqlite`; that database lives below `runtime/`.
+
 Local devserver runs do not require Redis. `CELERY_ENABLED` defaults to `false`, so campaign queue actions update database state without publishing Celery tasks. Use the synchronous send flow for local send tests, or set `CELERY_ENABLED=true` only when a Redis broker and worker are running.
 
-`requirements-dev.txt` links local `govoplan-files`, `govoplan-mail`, and `govoplan-campaign` checkouts for development. `requirements-release.txt` installs those modules from tagged git refs for release builds. See [RELEASE_DEPENDENCIES.md](docs/RELEASE_DEPENDENCIES.md).
+To run the production-like local profile with PostgreSQL, Redis, a Celery
+worker, explicit module configuration, and persistent local file storage:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/launch/launch-production-like-dev.sh
+```
+
+See `/mnt/DATA/git/govoplan/dev/production-like/README.md` for ports,
+environment overrides, and cleanup commands. Core keeps wrapper commands during
+the migration, but whole-product profiles are owned by the meta repository.
+
+## Security audit
+
+The repository includes a containerized audit toolbox for SAST, secret scanning,
+dependency checks, filesystem misconfiguration scans, duplication, and complexity
+reports. See [SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) for the operating model.
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/checks/security-audit/run.sh --mode ci --scope govoplan
+tools/checks/security-audit/run.sh --mode full --scope govoplan
+```
+
+CI runs the `ci` profile in report-only mode and uploads `audit-reports/` as an
+artifact. Once the baseline is clean, set `SECURITY_AUDIT_FAIL_ON_FINDINGS=1`
+or pass `--strict` locally to turn findings into a failing gate.
+
+`govoplan_core.devserver` enables the development bootstrap before loading settings. In dev, startup migrations create or upgrade the schema and the bootstrap creates the default development login if needed. Explicitly setting `DEV_BOOTSTRAP_ENABLED=false` disables this convenience. Production deployments should use migrations and managed database provisioning instead.
+
+To verify the effective runtime paths and bootstrap behavior without starting uvicorn, run the smoke mode:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.devserver --smoke --no-reload
+```
+
+The smoke mode prints the effective config, runtime root, database URL, modules, reload state, and bootstrap decision, then creates the ASGI app and runs startup once.
+
+The meta repository owns whole-product `requirements-dev.txt`,
+`requirements-release.txt`, and the root `.env.example` operator template. Core
+keeps package metadata and runtime commands. See
+[RELEASE_DEPENDENCIES.md](docs/RELEASE_DEPENDENCIES.md).
+
+For the install/runtime configuration contract and operator deployment flow, see [DEPLOYMENT_OPERATOR_GUIDE.md](docs/DEPLOYMENT_OPERATOR_GUIDE.md).
+For self-hosted config bootstrap and validation:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.commands.config env-template --profile self-hosted --generate-secrets
+/mnt/DATA/git/govoplan/.venv/bin/python -m govoplan_core.commands.config validate --profile self-hosted
+```
 
 ## WebUI development
 

alembic.ini

@@ -1,7 +1,8 @@
 [alembic]
 script_location = alembic
+path_separator = os
 prepend_sys_path = .
-sqlalchemy.url = sqlite:///./multimailer-dev.db
+sqlalchemy.url = sqlite:///./runtime/govoplan-dev.db
 
 [loggers]
 keys = root,sqlalchemy,alembic

alembic/dev_versions/0a1b2c3d4e6f_mail_profile_credential_usernames.py

@@ -0,0 +1,85 @@
+"""split mail profile usernames from server config
+
+Revision ID: 0a1b2c3d4e6f
+Revises: f5a6b7c8d9e0
+Create Date: 2026-06-25 15:20:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0a1b2c3d4e6f"
+down_revision = "f5a6b7c8d9e0"
+branch_labels = None
+depends_on = None
+
+
+def _profiles_table() -> sa.Table:
+    return sa.table(
+        "mail_server_profiles",
+        sa.column("id", sa.String(length=36)),
+        sa.column("smtp_config", sa.JSON()),
+        sa.column("smtp_username", sa.String(length=320)),
+        sa.column("imap_config", sa.JSON()),
+        sa.column("imap_username", sa.String(length=320)),
+    )
+
+
+def _without_username(value):
+    if not isinstance(value, dict):
+        return value, None
+    data = dict(value)
+    username = data.pop("username", None)
+    data.pop("enabled", None)
+    return data, username
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    if "mail_server_profiles" not in inspector.get_table_names():
+        return
+    columns = {column["name"] for column in inspector.get_columns("mail_server_profiles")}
+    if "smtp_username" not in columns:
+        op.add_column("mail_server_profiles", sa.Column("smtp_username", sa.String(length=320), nullable=True))
+    if "imap_username" not in columns:
+        op.add_column("mail_server_profiles", sa.Column("imap_username", sa.String(length=320), nullable=True))
+
+    profiles = _profiles_table()
+    rows = bind.execute(sa.select(profiles.c.id, profiles.c.smtp_config, profiles.c.smtp_username, profiles.c.imap_config, profiles.c.imap_username)).mappings().all()
+    for row in rows:
+        smtp_config, smtp_username = _without_username(row["smtp_config"] or {})
+        imap_config, imap_username = _without_username(row["imap_config"] or {}) if row["imap_config"] is not None else (None, None)
+        values = {
+            "smtp_config": smtp_config,
+            "imap_config": imap_config,
+        }
+        if row["smtp_username"] in (None, "") and smtp_username not in (None, ""):
+            values["smtp_username"] = str(smtp_username)
+        if row["imap_username"] in (None, "") and imap_username not in (None, ""):
+            values["imap_username"] = str(imap_username)
+        bind.execute(sa.update(profiles).where(profiles.c.id == row["id"]).values(**values))
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    if "mail_server_profiles" not in inspector.get_table_names():
+        return
+    columns = {column["name"] for column in inspector.get_columns("mail_server_profiles")}
+    profiles = _profiles_table()
+    if {"smtp_username", "imap_username"}.issubset(columns):
+        rows = bind.execute(sa.select(profiles.c.id, profiles.c.smtp_config, profiles.c.smtp_username, profiles.c.imap_config, profiles.c.imap_username)).mappings().all()
+        for row in rows:
+            smtp_config = dict(row["smtp_config"] or {})
+            if row["smtp_username"] not in (None, ""):
+                smtp_config["username"] = row["smtp_username"]
+            imap_config = dict(row["imap_config"] or {}) if row["imap_config"] is not None else None
+            if imap_config is not None and row["imap_username"] not in (None, ""):
+                imap_config["username"] = row["imap_username"]
+            bind.execute(sa.update(profiles).where(profiles.c.id == row["id"]).values(smtp_config=smtp_config, imap_config=imap_config))
+    if "imap_username" in columns:
+        op.drop_column("mail_server_profiles", "imap_username")
+    if "smtp_username" in columns:
+        op.drop_column("mail_server_profiles", "smtp_username")

alembic/dev_versions/0f1e2d3c4b5a_audit_outbox_events.py

@@ -0,0 +1,52 @@
+"""add audit outbox events to detailed dev track
+
+Revision ID: 0f1e2d3c4b5a
+Revises: 4f2a9c8e7b6d
+Create Date: 2026-07-11 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0f1e2d3c4b5a"
+down_revision = "4f2a9c8e7b6d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "audit_outbox_events",
+        sa.Column("id", sa.String(length=36), nullable=False),
+        sa.Column("event_id", sa.String(length=36), nullable=False),
+        sa.Column("event_type", sa.String(length=200), nullable=False),
+        sa.Column("module_id", sa.String(length=100), nullable=False),
+        sa.Column("correlation_id", sa.String(length=128), nullable=True),
+        sa.Column("causation_id", sa.String(length=128), nullable=True),
+        sa.Column("classification", sa.String(length=40), nullable=False),
+        sa.Column("payload", sa.JSON(), nullable=False),
+        sa.Column("status", sa.String(length=20), nullable=False),
+        sa.Column("attempts", sa.Integer(), nullable=False),
+        sa.Column("next_attempt_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("dispatched_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("last_error", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_audit_outbox_events")),
+        sa.UniqueConstraint("event_id", name="uq_audit_outbox_events_event_id"),
+    )
+    op.create_index("ix_audit_outbox_events_correlation_id", "audit_outbox_events", ["correlation_id"], unique=False)
+    op.create_index("ix_audit_outbox_events_event_type", "audit_outbox_events", ["event_type"], unique=False)
+    op.create_index(op.f("ix_audit_outbox_events_status"), "audit_outbox_events", ["status"], unique=False)
+    op.create_index(
+        "ix_audit_outbox_events_status_next_attempt_at",
+        "audit_outbox_events",
+        ["status", "next_attempt_at"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("audit_outbox_events")

alembic/dev_versions/1b2c3d4e5f70_drop_mail_credential_override_policy.py

@@ -0,0 +1,108 @@
+"""drop mail credential override policy fields
+
+Revision ID: 1b2c3d4e5f70
+Revises: 0a1b2c3d4e6f
+Create Date: 2026-06-25 18:30:00.000000
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "1b2c3d4e5f70"
+down_revision = "0a1b2c3d4e6f"
+branch_labels = None
+depends_on = None
+
+_MAIL_POLICY_KEY = "mail_profile_policy"
+_CREDENTIAL_KEYS = ("smtp_credentials", "imap_credentials")
+_DEPRECATED_LIMIT_KEYS = ("smtp_credentials.allow_override", "imap_credentials.allow_override")
+
+
+def _json_table(table_name: str, column_name: str) -> sa.Table:
+    return sa.table(
+        table_name,
+        sa.column("id", sa.String(length=36)),
+        sa.column(column_name, sa.JSON()),
+    )
+
+
+def _as_dict(value: Any) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        return dict(value)
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return None
+        return dict(parsed) if isinstance(parsed, dict) else None
+    return None
+
+
+def _scrub_policy(value: Any) -> tuple[dict[str, Any] | None, bool]:
+    policy = _as_dict(value)
+    if policy is None:
+        return None, False
+    changed = False
+
+    for key in _CREDENTIAL_KEYS:
+        credential = _as_dict(policy.get(key))
+        if credential is not None and "allow_override" in credential:
+            credential.pop("allow_override", None)
+            policy[key] = credential
+            changed = True
+
+    limits = _as_dict(policy.get("allow_lower_level_limits"))
+    if limits is not None:
+        for key in _DEPRECATED_LIMIT_KEYS:
+            if key in limits:
+                limits.pop(key, None)
+                changed = True
+        if changed:
+            policy["allow_lower_level_limits"] = limits
+
+    return policy, changed
+
+
+def _scrub_settings_table(table_name: str) -> None:
+    bind = op.get_bind()
+    table = _json_table(table_name, "settings")
+    rows = bind.execute(sa.select(table.c.id, table.c.settings)).mappings().all()
+    for row in rows:
+        settings = _as_dict(row["settings"])
+        if settings is None:
+            continue
+        policy, changed = _scrub_policy(settings.get(_MAIL_POLICY_KEY))
+        if changed and policy is not None:
+            settings[_MAIL_POLICY_KEY] = policy
+            bind.execute(sa.update(table).where(table.c.id == row["id"]).values(settings=settings))
+
+
+def _scrub_policy_column(table_name: str) -> None:
+    bind = op.get_bind()
+    table = _json_table(table_name, "mail_profile_policy")
+    rows = bind.execute(sa.select(table.c.id, table.c.mail_profile_policy)).mappings().all()
+    for row in rows:
+        policy, changed = _scrub_policy(row["mail_profile_policy"])
+        if changed and policy is not None:
+            bind.execute(sa.update(table).where(table.c.id == row["id"]).values(mail_profile_policy=policy))
+
+
+def upgrade() -> None:
+    inspector = sa.inspect(op.get_bind())
+    tables = set(inspector.get_table_names())
+    for table_name in ("core_system_settings", "tenancy_tenants"):
+        if table_name in tables and "settings" in {column["name"] for column in inspector.get_columns(table_name)}:
+            _scrub_settings_table(table_name)
+    for table_name in ("access_users", "access_groups", "campaigns"):
+        if table_name in tables and "mail_profile_policy" in {column["name"] for column in inspector.get_columns(table_name)}:
+            _scrub_policy_column(table_name)
+
+
+def downgrade() -> None:
+    # The removed fields are redundant with the surviving lower-level limit
+    # switches, so they cannot be reconstructed safely.
+    pass

alembic/dev_versions/1f8d4c2a0b7e_editable_campaign_versions.py

@@ -30,7 +30,7 @@ def upgrade() -> None:
         batch_op.add_column(sa.Column("locked_by_user_id", sa.String(length=36), nullable=True))
         batch_op.create_foreign_key(
             op.f("fk_campaign_versions_locked_by_user_id_users"),
-            "users",
+            "access_users",
             ["locked_by_user_id"],
             ["id"],
             ondelete="SET NULL",

alembic/dev_versions/2c3d4e5f6a7b_auth_sessions_and_rbac.py

@@ -0,0 +1,130 @@
+"""auth sessions and RBAC assignments
+
+Revision ID: 2c3d4e5f6a7b
+Revises: 1f8d4c2a0b7e
+Create Date: 2026-06-08 10:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "2c3d4e5f6a7b"
+down_revision = "1f8d4c2a0b7e"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("access_users") as batch_op:
+        batch_op.add_column(sa.Column("auth_provider", sa.String(length=50), nullable=False, server_default="local"))
+        batch_op.add_column(sa.Column("password_hash", sa.String(length=500), nullable=True))
+        batch_op.add_column(sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True))
+
+    op.create_table(
+        "access_user_group_memberships",
+        sa.Column("id", sa.String(length=36), nullable=False),
+        sa.Column("tenant_id", sa.String(length=36), nullable=False),
+        sa.Column("user_id", sa.String(length=36), nullable=False),
+        sa.Column("group_id", sa.String(length=36), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["access_users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["group_id"], ["access_groups.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("tenant_id", "user_id", "group_id", name="uq_user_group_memberships"),
+    )
+    op.create_index(op.f("ix_access_user_group_memberships_tenant_id"), "access_user_group_memberships", ["tenant_id"])
+    op.create_index(op.f("ix_access_user_group_memberships_user_id"), "access_user_group_memberships", ["user_id"])
+    op.create_index(op.f("ix_access_user_group_memberships_group_id"), "access_user_group_memberships", ["group_id"])
+
+    op.create_table(
+        "access_user_role_assignments",
+        sa.Column("id", sa.String(length=36), nullable=False),
+        sa.Column("tenant_id", sa.String(length=36), nullable=False),
+        sa.Column("user_id", sa.String(length=36), nullable=False),
+        sa.Column("role_id", sa.String(length=36), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["access_users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["role_id"], ["access_roles.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("tenant_id", "user_id", "role_id", name="uq_user_role_assignments"),
+    )
+    op.create_index(op.f("ix_access_user_role_assignments_tenant_id"), "access_user_role_assignments", ["tenant_id"])
+    op.create_index(op.f("ix_access_user_role_assignments_user_id"), "access_user_role_assignments", ["user_id"])
+    op.create_index(op.f("ix_access_user_role_assignments_role_id"), "access_user_role_assignments", ["role_id"])
+
+    op.create_table(
+        "access_group_role_assignments",
+        sa.Column("id", sa.String(length=36), nullable=False),
+        sa.Column("tenant_id", sa.String(length=36), nullable=False),
+        sa.Column("group_id", sa.String(length=36), nullable=False),
+        sa.Column("role_id", sa.String(length=36), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["group_id"], ["access_groups.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["role_id"], ["access_roles.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("tenant_id", "group_id", "role_id", name="uq_group_role_assignments"),
+    )
+    op.create_index(op.f("ix_access_group_role_assignments_tenant_id"), "access_group_role_assignments", ["tenant_id"])
+    op.create_index(op.f("ix_access_group_role_assignments_group_id"), "access_group_role_assignments", ["group_id"])
+    op.create_index(op.f("ix_access_group_role_assignments_role_id"), "access_group_role_assignments", ["role_id"])
+
+    op.create_table(
+        "access_auth_sessions",
+        sa.Column("id", sa.String(length=36), nullable=False),
+        sa.Column("tenant_id", sa.String(length=36), nullable=False),
+        sa.Column("user_id", sa.String(length=36), nullable=False),
+        sa.Column("token_hash", sa.String(length=128), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("user_agent", sa.String(length=500), nullable=True),
+        sa.Column("ip_address", sa.String(length=100), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["access_users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("token_hash"),
+    )
+    op.create_index(op.f("ix_access_auth_sessions_tenant_id"), "access_auth_sessions", ["tenant_id"])
+    op.create_index(op.f("ix_access_auth_sessions_user_id"), "access_auth_sessions", ["user_id"])
+    op.create_index(op.f("ix_access_auth_sessions_token_hash"), "access_auth_sessions", ["token_hash"])
+    op.create_index(op.f("ix_access_auth_sessions_expires_at"), "access_auth_sessions", ["expires_at"])
+    op.create_index(op.f("ix_access_auth_sessions_revoked_at"), "access_auth_sessions", ["revoked_at"])
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_access_auth_sessions_revoked_at"), table_name="access_auth_sessions")
+    op.drop_index(op.f("ix_access_auth_sessions_expires_at"), table_name="access_auth_sessions")
+    op.drop_index(op.f("ix_access_auth_sessions_token_hash"), table_name="access_auth_sessions")
+    op.drop_index(op.f("ix_access_auth_sessions_user_id"), table_name="access_auth_sessions")
+    op.drop_index(op.f("ix_access_auth_sessions_tenant_id"), table_name="access_auth_sessions")
+    op.drop_table("access_auth_sessions")
+
+    op.drop_index(op.f("ix_access_group_role_assignments_role_id"), table_name="access_group_role_assignments")
+    op.drop_index(op.f("ix_access_group_role_assignments_group_id"), table_name="access_group_role_assignments")
+    op.drop_index(op.f("ix_access_group_role_assignments_tenant_id"), table_name="access_group_role_assignments")
+    op.drop_table("access_group_role_assignments")
+
+    op.drop_index(op.f("ix_access_user_role_assignments_role_id"), table_name="access_user_role_assignments")
+    op.drop_index(op.f("ix_access_user_role_assignments_user_id"), table_name="access_user_role_assignments")
+    op.drop_index(op.f("ix_access_user_role_assignments_tenant_id"), table_name="access_user_role_assignments")
+    op.drop_table("access_user_role_assignments")
+
+    op.drop_index(op.f("ix_access_user_group_memberships_group_id"), table_name="access_user_group_memberships")
+    op.drop_index(op.f("ix_access_user_group_memberships_user_id"), table_name="access_user_group_memberships")
+    op.drop_index(op.f("ix_access_user_group_memberships_tenant_id"), table_name="access_user_group_memberships")
+    op.drop_table("access_user_group_memberships")
+
+    with op.batch_alter_table("access_users") as batch_op:
+        batch_op.drop_column("last_login_at")
+        batch_op.drop_column("password_hash")
+        batch_op.drop_column("auth_provider")

alembic/dev_versions/2e3f4a5b6c7d_namespace_platform_tables.py

@@ -0,0 +1,78 @@
+"""namespace platform-owned tables
+
+Revision ID: 2e3f4a5b6c7d
+Revises: 1b2c3d4e5f70
+Create Date: 2026-07-09 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "2e3f4a5b6c7d"
+down_revision = "1b2c3d4e5f70"
+branch_labels = None
+depends_on = None
+
+_TABLE_RENAMES = (
+    ("tenants", "tenancy_tenants"),
+    ("accounts", "access_accounts"),
+    ("users", "access_users"),
+    ("groups", "access_groups"),
+    ("roles", "access_roles"),
+    ("system_role_assignments", "access_system_role_assignments"),
+    ("user_group_memberships", "access_user_group_memberships"),
+    ("user_role_assignments", "access_user_role_assignments"),
+    ("group_role_assignments", "access_group_role_assignments"),
+    ("api_keys", "access_api_keys"),
+    ("auth_sessions", "access_auth_sessions"),
+    ("system_settings", "core_system_settings"),
+    ("governance_templates", "admin_governance_templates"),
+    ("governance_template_assignments", "admin_governance_template_assignments"),
+)
+
+
+def _row_count(bind: sa.Connection, table_name: str) -> int:
+    return int(bind.execute(sa.text(f"SELECT COUNT(*) FROM {table_name}")).scalar_one())
+
+
+def _rename_tables(renames: tuple[tuple[str, str], ...]) -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    tables = set(inspector.get_table_names())
+
+    old_tables_to_drop: set[str] = set()
+    new_tables_to_drop: set[str] = set()
+    for old_name, new_name in renames:
+        if old_name not in tables or new_name not in tables:
+            continue
+        if _row_count(bind, old_name) == 0:
+            old_tables_to_drop.add(old_name)
+        elif _row_count(bind, new_name) == 0:
+            new_tables_to_drop.add(new_name)
+        else:
+            raise RuntimeError(f"Cannot rename non-empty {old_name} over non-empty {new_name}")
+
+    for old_name, _new_name in reversed(renames):
+        if old_name in old_tables_to_drop:
+            op.drop_table(old_name)
+            tables.remove(old_name)
+    for _old_name, new_name in reversed(renames):
+        if new_name in new_tables_to_drop:
+            op.drop_table(new_name)
+            tables.remove(new_name)
+
+    for old_name, new_name in renames:
+        if old_name not in tables:
+            continue
+        op.rename_table(old_name, new_name)
+        tables.remove(old_name)
+        tables.add(new_name)
+
+
+def upgrade() -> None:
+    _rename_tables(_TABLE_RENAMES)
+
+
+def downgrade() -> None:
+    _rename_tables(tuple((new_name, old_name) for old_name, new_name in reversed(_TABLE_RENAMES)))

alembic/dev_versions/3d4e5f6a7b8c_file_storage_backend.py

@@ -32,7 +32,7 @@ def upgrade() -> None:
         sa.Column("retained_until", sa.DateTime(timezone=True), nullable=True),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("tenant_id", "checksum_sha256", "size_bytes", name="uq_file_blobs_tenant_checksum_size"),
     )
@@ -55,10 +55,10 @@ def upgrade() -> None:
         sa.Column("metadata", sa.JSON(), nullable=True),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["owner_group_id"], ["groups.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["owner_user_id"], ["users.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["owner_group_id"], ["access_groups.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["owner_user_id"], ["access_users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
     )
     for col in ["tenant_id", "owner_type", "owner_user_id", "owner_group_id", "current_version_id", "display_path", "filename", "created_by_user_id", "deleted_at"]:
@@ -80,9 +80,9 @@ def upgrade() -> None:
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
         sa.ForeignKeyConstraint(["blob_id"], ["file_blobs.id"], ondelete="RESTRICT"),
-        sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
         sa.ForeignKeyConstraint(["file_asset_id"], ["file_assets.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("file_asset_id", "version_number", name="uq_file_versions_asset_number"),
     )
@@ -101,9 +101,9 @@ def upgrade() -> None:
         sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
         sa.ForeignKeyConstraint(["file_asset_id"], ["file_assets.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("file_asset_id", "target_type", "target_id", "revoked_at", name="uq_file_shares_active_target"),
     )
@@ -136,7 +136,7 @@ def upgrade() -> None:
         sa.ForeignKeyConstraint(["file_asset_id"], ["file_assets.id"], ondelete="RESTRICT"),
         sa.ForeignKeyConstraint(["file_blob_id"], ["file_blobs.id"], ondelete="RESTRICT"),
         sa.ForeignKeyConstraint(["file_version_id"], ["file_versions.id"], ondelete="RESTRICT"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("campaign_job_id", "file_version_id", "filename_used", "use_stage", name="uq_campaign_attachment_uses_job_file_stage"),
     )

alembic/dev_versions/3f4a5b6c7d8e_core_change_sequence.py

@@ -0,0 +1,111 @@
+"""add core change sequence
+
+Revision ID: 3f4a5b6c7d8e
+Revises: 2e3f4a5b6c7d
+Create Date: 2026-07-09 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "3f4a5b6c7d8e"
+down_revision = "2e3f4a5b6c7d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    inspector = sa.inspect(op.get_bind())
+    if "core_change_sequence" not in inspector.get_table_names():
+        op.create_table(
+            "core_change_sequence",
+            sa.Column("id", sa.BigInteger().with_variant(sa.Integer(), "sqlite"), autoincrement=True, nullable=False),
+            sa.Column("tenant_id", sa.String(length=36), nullable=True),
+            sa.Column("module_id", sa.String(length=100), nullable=False),
+            sa.Column("collection", sa.String(length=150), nullable=False),
+            sa.Column("resource_type", sa.String(length=100), nullable=False),
+            sa.Column("resource_id", sa.String(length=255), nullable=False),
+            sa.Column("operation", sa.String(length=30), nullable=False),
+            sa.Column("actor_type", sa.String(length=30), nullable=True),
+            sa.Column("actor_id", sa.String(length=255), nullable=True),
+            sa.Column("payload", sa.JSON(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_core_change_sequence")),
+        )
+
+    inspector = sa.inspect(op.get_bind())
+    indexes = {item["name"] for item in inspector.get_indexes("core_change_sequence")}
+    for column in (
+        "tenant_id",
+        "module_id",
+        "collection",
+        "resource_type",
+        "resource_id",
+        "operation",
+        "actor_type",
+        "actor_id",
+        "created_at",
+    ):
+        name = op.f(f"ix_core_change_sequence_{column}")
+        if name not in indexes:
+            op.create_index(name, "core_change_sequence", [column], unique=False)
+    for name, columns in (
+        ("ix_core_change_sequence_tenant_module_id", ["tenant_id", "module_id", "id"]),
+        ("ix_core_change_sequence_collection_id", ["collection", "id"]),
+        ("ix_core_change_sequence_resource", ["module_id", "resource_type", "resource_id"]),
+    ):
+        if name not in indexes:
+            op.create_index(name, "core_change_sequence", columns, unique=False)
+
+    inspector = sa.inspect(op.get_bind())
+    if "core_change_sequence_retention_floor" not in inspector.get_table_names():
+        op.create_table(
+            "core_change_sequence_retention_floor",
+            sa.Column("id", sa.BigInteger().with_variant(sa.Integer(), "sqlite"), autoincrement=True, nullable=False),
+            sa.Column("tenant_key", sa.String(length=36), nullable=False),
+            sa.Column("module_id", sa.String(length=100), nullable=False),
+            sa.Column("collection", sa.String(length=150), nullable=False),
+            sa.Column("min_valid_sequence", sa.BigInteger().with_variant(sa.Integer(), "sqlite"), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_core_change_sequence_retention_floor")),
+            sa.UniqueConstraint("tenant_key", "module_id", "collection", name="uq_core_change_sequence_retention_scope"),
+        )
+    indexes = {item["name"] for item in inspector.get_indexes("core_change_sequence_retention_floor")}
+    if "ix_core_change_sequence_retention_scope" not in indexes:
+        op.create_index(
+            "ix_core_change_sequence_retention_scope",
+            "core_change_sequence_retention_floor",
+            ["tenant_key", "module_id", "collection"],
+            unique=False,
+        )
+
+
+def downgrade() -> None:
+    inspector = sa.inspect(op.get_bind())
+    if "core_change_sequence_retention_floor" in inspector.get_table_names():
+        indexes = {item["name"] for item in inspector.get_indexes("core_change_sequence_retention_floor")}
+        if "ix_core_change_sequence_retention_scope" in indexes:
+            op.drop_index("ix_core_change_sequence_retention_scope", table_name="core_change_sequence_retention_floor")
+        op.drop_table("core_change_sequence_retention_floor")
+    if "core_change_sequence" not in inspector.get_table_names():
+        return
+    indexes = {item["name"] for item in inspector.get_indexes("core_change_sequence")}
+    for name in (
+        "ix_core_change_sequence_resource",
+        "ix_core_change_sequence_collection_id",
+        "ix_core_change_sequence_tenant_module_id",
+        op.f("ix_core_change_sequence_created_at"),
+        op.f("ix_core_change_sequence_actor_id"),
+        op.f("ix_core_change_sequence_actor_type"),
+        op.f("ix_core_change_sequence_operation"),
+        op.f("ix_core_change_sequence_resource_id"),
+        op.f("ix_core_change_sequence_resource_type"),
+        op.f("ix_core_change_sequence_collection"),
+        op.f("ix_core_change_sequence_module_id"),
+        op.f("ix_core_change_sequence_tenant_id"),
+    ):
+        if name in indexes:
+            op.drop_index(name, table_name="core_change_sequence")
+    op.drop_table("core_change_sequence")

alembic/dev_versions/4e5f6a7b8c9d_file_folders.py

@@ -31,10 +31,10 @@ def upgrade() -> None:
         sa.Column("metadata", sa.JSON(), nullable=True),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["owner_group_id"], ["groups.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["owner_user_id"], ["users.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["owner_group_id"], ["access_groups.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["owner_user_id"], ["access_users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
     )
     for col in ["tenant_id", "owner_type", "owner_user_id", "owner_group_id", "path", "created_by_user_id", "deleted_at"]:

alembic/dev_versions/4f2a9c8e7b6d_rename_tenancy_tenants_to_core_scopes.py

@@ -0,0 +1,76 @@
+"""rename tenancy scope table to core scopes
+
+Revision ID: 4f2a9c8e7b6d
+Revises: 3f4a5b6c7d8e
+Create Date: 2026-07-10 00:00:00.000000
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "4f2a9c8e7b6d"
+down_revision = "3f4a5b6c7d8e"
+branch_labels = None
+depends_on = None
+
+LEGACY_SCOPE_TABLE = "tenancy_tenants"
+CORE_SCOPE_TABLE = "core_scopes"
+LEGACY_SLUG_INDEX = "ix_tenancy_tenants_slug"
+CORE_SLUG_INDEX = "ix_core_scopes_slug"
+
+
+def _row_count(bind: sa.Connection, table_name: str) -> int:
+    quoted = bind.dialect.identifier_preparer.quote(table_name)
+    return int(bind.execute(sa.text(f"SELECT COUNT(*) FROM {quoted}")).scalar_one())
+
+
+def _scope_tables(bind: sa.Connection) -> set[str]:
+    return set(sa.inspect(bind).get_table_names())
+
+
+def _drop_table_if_empty(bind: sa.Connection, table_name: str) -> bool:
+    if _row_count(bind, table_name) != 0:
+        return False
+    op.drop_table(table_name)
+    return True
+
+
+def _ensure_slug_index(bind: sa.Connection, table_name: str, index_name: str, old_index_name: str) -> None:
+    indexes = {index["name"] for index in sa.inspect(bind).get_indexes(table_name)}
+    if old_index_name in indexes:
+        op.drop_index(old_index_name, table_name=table_name)
+        indexes.remove(old_index_name)
+    if index_name not in indexes:
+        op.create_index(op.f(index_name), table_name, ["slug"], unique=True)
+
+
+def _rename_scope_table(old_name: str, new_name: str) -> None:
+    bind = op.get_bind()
+    tables = _scope_tables(bind)
+    if old_name not in tables:
+        if new_name in tables:
+            _ensure_slug_index(bind, new_name, CORE_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else LEGACY_SLUG_INDEX, LEGACY_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else CORE_SLUG_INDEX)
+        return
+
+    if new_name in tables:
+        if _drop_table_if_empty(bind, new_name):
+            tables.remove(new_name)
+        elif _drop_table_if_empty(bind, old_name):
+            _ensure_slug_index(bind, new_name, CORE_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else LEGACY_SLUG_INDEX, LEGACY_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else CORE_SLUG_INDEX)
+            return
+        else:
+            raise RuntimeError(f"Cannot reconcile non-empty {old_name} over non-empty {new_name}")
+
+    if old_name in tables and new_name not in tables:
+        op.rename_table(old_name, new_name)
+        _ensure_slug_index(bind, new_name, CORE_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else LEGACY_SLUG_INDEX, LEGACY_SLUG_INDEX if new_name == CORE_SCOPE_TABLE else CORE_SLUG_INDEX)
+
+
+def upgrade() -> None:
+    _rename_scope_table(LEGACY_SCOPE_TABLE, CORE_SCOPE_TABLE)
+
+
+def downgrade() -> None:
+    _rename_scope_table(CORE_SCOPE_TABLE, LEGACY_SCOPE_TABLE)

alembic/dev_versions/5f6a7b8c9d0e_campaign_version_user_locks.py

@@ -24,7 +24,7 @@ def upgrade() -> None:
         batch_op.add_column(sa.Column("user_locked_by_user_id", sa.String(length=36), nullable=True))
         batch_op.create_foreign_key(
             "fk_campaign_versions_user_locked_by_user_id_users",
-            "users",
+            "access_users",
             ["user_locked_by_user_id"],
             ["id"],
             ondelete="SET NULL",

alembic/dev_versions/8c9d0e1f2a3b_accounts_tenant_admin_rbac.py

@@ -62,25 +62,25 @@ def upgrade() -> None:
     bind = op.get_bind()
     inspector = sa.inspect(bind)
     tables = set(inspector.get_table_names())
-    user_columns = {column["name"] for column in inspector.get_columns("users")}
+    user_columns = {column["name"] for column in inspector.get_columns("access_users")}
     # Base.metadata.create_all() from a newer application can create brand-new
     # tables while leaving existing tables unaltered. Repair that known drift by
     # removing only empty, unreferenced administration tables before applying the
     # real migration. A non-empty table is never guessed at or discarded.
-    if "account_id" not in user_columns and "system_role_assignments" in tables:
-        count = bind.execute(sa.text("SELECT COUNT(*) FROM system_role_assignments")).scalar_one()
+    if "account_id" not in user_columns and "access_system_role_assignments" in tables:
+        count = bind.execute(sa.text("SELECT COUNT(*) FROM access_system_role_assignments")).scalar_one()
         if count:
             raise RuntimeError("Cannot reconcile non-empty create_all system_role_assignments table")
-        op.drop_table("system_role_assignments")
-        tables.remove("system_role_assignments")
-    if "account_id" not in user_columns and "accounts" in tables:
-        count = bind.execute(sa.text("SELECT COUNT(*) FROM accounts")).scalar_one()
+        op.drop_table("access_system_role_assignments")
+        tables.remove("access_system_role_assignments")
+    if "account_id" not in user_columns and "access_accounts" in tables:
+        count = bind.execute(sa.text("SELECT COUNT(*) FROM access_accounts")).scalar_one()
         if count:
             raise RuntimeError("Cannot reconcile non-empty create_all accounts table")
-        op.drop_table("accounts")
+        op.drop_table("access_accounts")
 
     op.create_table(
-        "accounts",
+        "access_accounts",
         sa.Column("id", sa.String(length=36), nullable=False),
         sa.Column("email", sa.String(length=320), nullable=False),
         sa.Column("normalized_email", sa.String(length=320), nullable=False),
@@ -95,29 +95,29 @@ def upgrade() -> None:
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("normalized_email", name="uq_accounts_normalized_email"),
     )
-    op.create_index(op.f("ix_accounts_normalized_email"), "accounts", ["normalized_email"])
+    op.create_index(op.f("ix_access_accounts_normalized_email"), "access_accounts", ["normalized_email"])
 
-    with op.batch_alter_table("tenants") as batch_op:
+    with op.batch_alter_table("tenancy_tenants") as batch_op:
         batch_op.add_column(sa.Column("description", sa.Text(), nullable=True))
         batch_op.add_column(sa.Column("default_locale", sa.String(length=20), nullable=False, server_default="en"))
         batch_op.add_column(sa.Column("settings", sa.JSON(), nullable=False, server_default="{}"))
 
-    with op.batch_alter_table("groups") as batch_op:
+    with op.batch_alter_table("access_groups") as batch_op:
         batch_op.add_column(sa.Column("description", sa.Text(), nullable=True))
         batch_op.add_column(sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()))
 
-    with op.batch_alter_table("roles") as batch_op:
+    with op.batch_alter_table("access_roles") as batch_op:
         batch_op.add_column(sa.Column("description", sa.Text(), nullable=True))
         batch_op.add_column(sa.Column("is_builtin", sa.Boolean(), nullable=False, server_default=sa.false()))
         batch_op.add_column(sa.Column("is_assignable", sa.Boolean(), nullable=False, server_default=sa.true()))
 
-    with op.batch_alter_table("users") as batch_op:
+    with op.batch_alter_table("access_users") as batch_op:
         batch_op.add_column(sa.Column("account_id", sa.String(length=36), nullable=True))
-    with op.batch_alter_table("auth_sessions") as batch_op:
+    with op.batch_alter_table("access_auth_sessions") as batch_op:
         batch_op.add_column(sa.Column("account_id", sa.String(length=36), nullable=True))
 
     users = bind.execute(sa.text(
-        "SELECT id, tenant_id, email, display_name, is_active, is_tenant_admin, auth_provider, password_hash, last_login_at, created_at, updated_at FROM users ORDER BY created_at, id"
+        "SELECT id, tenant_id, email, display_name, is_active, is_tenant_admin, auth_provider, password_hash, last_login_at, created_at, updated_at FROM access_users ORDER BY created_at, id"
     )).mappings().all()
 
     accounts_by_email: dict[str, str] = {}
@@ -155,7 +155,7 @@ def upgrade() -> None:
             first_system_owner_account_id = account_id
 
     accounts_table = sa.table(
-        "accounts",
+        "access_accounts",
         sa.column("id", sa.String), sa.column("email", sa.String), sa.column("normalized_email", sa.String),
         sa.column("display_name", sa.String), sa.column("is_active", sa.Boolean), sa.column("auth_provider", sa.String),
         sa.column("password_hash", sa.String), sa.column("password_reset_required", sa.Boolean),
@@ -166,54 +166,54 @@ def upgrade() -> None:
         bind.execute(accounts_table.insert(), list(account_rows.values()))
     for row in users:
         bind.execute(
-            sa.text("UPDATE users SET account_id = :account_id WHERE id = :user_id"),
+            sa.text("UPDATE access_users SET account_id = :account_id WHERE id = :user_id"),
             {"account_id": accounts_by_email[_normalize_email(row["email"])], "user_id": row["id"]},
         )
     bind.execute(sa.text(
-        "UPDATE auth_sessions SET account_id = (SELECT users.account_id FROM users WHERE users.id = auth_sessions.user_id)"
+        "UPDATE access_auth_sessions SET account_id = (SELECT access_users.account_id FROM access_users WHERE access_users.id = access_auth_sessions.user_id)"
     ))
 
-    with op.batch_alter_table("users") as batch_op:
+    with op.batch_alter_table("access_users") as batch_op:
         batch_op.alter_column("account_id", existing_type=sa.String(length=36), nullable=False)
-        batch_op.create_foreign_key("fk_users_account_id_accounts", "accounts", ["account_id"], ["id"], ondelete="CASCADE")
+        batch_op.create_foreign_key("fk_users_account_id_accounts", "access_accounts", ["account_id"], ["id"], ondelete="CASCADE")
         batch_op.create_unique_constraint("uq_users_tenant_account", ["tenant_id", "account_id"])
-    op.create_index(op.f("ix_users_account_id"), "users", ["account_id"])
+    op.create_index(op.f("ix_access_users_account_id"), "access_users", ["account_id"])
 
-    with op.batch_alter_table("auth_sessions") as batch_op:
+    with op.batch_alter_table("access_auth_sessions") as batch_op:
         batch_op.alter_column("account_id", existing_type=sa.String(length=36), nullable=False)
-        batch_op.create_foreign_key("fk_auth_sessions_account_id_accounts", "accounts", ["account_id"], ["id"], ondelete="CASCADE")
-    op.create_index(op.f("ix_auth_sessions_account_id"), "auth_sessions", ["account_id"])
+        batch_op.create_foreign_key("fk_auth_sessions_account_id_accounts", "access_accounts", ["account_id"], ["id"], ondelete="CASCADE")
+    op.create_index(op.f("ix_access_auth_sessions_account_id"), "access_auth_sessions", ["account_id"])
 
     op.create_table(
-        "system_role_assignments",
+        "access_system_role_assignments",
         sa.Column("id", sa.String(length=36), nullable=False),
         sa.Column("account_id", sa.String(length=36), nullable=False),
         sa.Column("role_id", sa.String(length=36), nullable=False),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["account_id"], ["accounts.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["role_id"], ["roles.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["account_id"], ["access_accounts.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["role_id"], ["access_roles.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("account_id", "role_id", name="uq_system_role_assignments"),
     )
-    op.create_index(op.f("ix_system_role_assignments_account_id"), "system_role_assignments", ["account_id"])
-    op.create_index(op.f("ix_system_role_assignments_role_id"), "system_role_assignments", ["role_id"])
+    op.create_index(op.f("ix_access_system_role_assignments_account_id"), "access_system_role_assignments", ["account_id"])
+    op.create_index(op.f("ix_access_system_role_assignments_role_id"), "access_system_role_assignments", ["role_id"])
 
     roles_table = sa.table(
-        "roles",
+        "access_roles",
         sa.column("id", sa.String), sa.column("tenant_id", sa.String), sa.column("slug", sa.String),
         sa.column("name", sa.String), sa.column("description", sa.Text), sa.column("permissions", sa.JSON),
         sa.column("is_builtin", sa.Boolean), sa.column("is_assignable", sa.Boolean),
         sa.column("created_at", sa.DateTime(timezone=True)), sa.column("updated_at", sa.DateTime(timezone=True)),
     )
     now = _now()
-    tenant_ids = [row[0] for row in bind.execute(sa.text("SELECT id FROM tenants")).all()]
+    tenant_ids = [row[0] for row in bind.execute(sa.text("SELECT id FROM tenancy_tenants")).all()]
     definitions = _role_definitions()
     tenant_role_ids: dict[tuple[str, str], str] = {}
     for tenant_id in tenant_ids:
         for slug, definition in definitions.items():
             existing = bind.execute(
-                sa.text("SELECT id FROM roles WHERE tenant_id = :tenant_id AND slug = :slug"),
+                sa.text("SELECT id FROM access_roles WHERE tenant_id = :tenant_id AND slug = :slug"),
                 {"tenant_id": tenant_id, "slug": slug},
             ).scalar_one_or_none()
             if existing:
@@ -253,7 +253,7 @@ def upgrade() -> None:
 
     op.create_index(
         "uq_roles_system_slug",
-        "roles",
+        "access_roles",
         ["slug"],
         unique=True,
         sqlite_where=sa.text("tenant_id IS NULL"),
@@ -267,11 +267,11 @@ def upgrade() -> None:
             continue
         owner_role_id = tenant_role_ids[(row["tenant_id"], "owner")]
         exists = bind.execute(sa.text(
-            "SELECT 1 FROM user_role_assignments WHERE tenant_id = :tenant_id AND user_id = :user_id AND role_id = :role_id"
+            "SELECT 1 FROM access_user_role_assignments WHERE tenant_id = :tenant_id AND user_id = :user_id AND role_id = :role_id"
         ), {"tenant_id": row["tenant_id"], "user_id": row["id"], "role_id": owner_role_id}).first()
         if not exists:
             bind.execute(sa.text(
-                "INSERT INTO user_role_assignments (id, tenant_id, user_id, role_id, created_at, updated_at) VALUES (:id, :tenant_id, :user_id, :role_id, :created_at, :updated_at)"
+                "INSERT INTO access_user_role_assignments (id, tenant_id, user_id, role_id, created_at, updated_at) VALUES (:id, :tenant_id, :user_id, :role_id, :created_at, :updated_at)"
             ), {"id": str(uuid.uuid4()), "tenant_id": row["tenant_id"], "user_id": row["id"], "role_id": owner_role_id, "created_at": now, "updated_at": now})
 
     # Bootstrap rule for existing installations: the earliest active legacy
@@ -284,40 +284,40 @@ def upgrade() -> None:
         ), None)
     if first_system_owner_account_id:
         bind.execute(sa.text(
-            "INSERT INTO system_role_assignments (id, account_id, role_id, created_at, updated_at) VALUES (:id, :account_id, :role_id, :created_at, :updated_at)"
+            "INSERT INTO access_system_role_assignments (id, account_id, role_id, created_at, updated_at) VALUES (:id, :account_id, :role_id, :created_at, :updated_at)"
         ), {"id": str(uuid.uuid4()), "account_id": first_system_owner_account_id, "role_id": system_owner_role_id, "created_at": now, "updated_at": now})
 
 
 def downgrade() -> None:
-    op.drop_index("uq_roles_system_slug", table_name="roles")
-    op.drop_index(op.f("ix_system_role_assignments_role_id"), table_name="system_role_assignments")
-    op.drop_index(op.f("ix_system_role_assignments_account_id"), table_name="system_role_assignments")
-    op.drop_table("system_role_assignments")
+    op.drop_index("uq_roles_system_slug", table_name="access_roles")
+    op.drop_index(op.f("ix_access_system_role_assignments_role_id"), table_name="access_system_role_assignments")
+    op.drop_index(op.f("ix_access_system_role_assignments_account_id"), table_name="access_system_role_assignments")
+    op.drop_table("access_system_role_assignments")
 
-    op.drop_index(op.f("ix_auth_sessions_account_id"), table_name="auth_sessions")
-    with op.batch_alter_table("auth_sessions") as batch_op:
+    op.drop_index(op.f("ix_access_auth_sessions_account_id"), table_name="access_auth_sessions")
+    with op.batch_alter_table("access_auth_sessions") as batch_op:
         batch_op.drop_constraint("fk_auth_sessions_account_id_accounts", type_="foreignkey")
         batch_op.drop_column("account_id")
 
-    op.drop_index(op.f("ix_users_account_id"), table_name="users")
-    with op.batch_alter_table("users") as batch_op:
+    op.drop_index(op.f("ix_access_users_account_id"), table_name="access_users")
+    with op.batch_alter_table("access_users") as batch_op:
         batch_op.drop_constraint("uq_users_tenant_account", type_="unique")
         batch_op.drop_constraint("fk_users_account_id_accounts", type_="foreignkey")
         batch_op.drop_column("account_id")
 
-    with op.batch_alter_table("roles") as batch_op:
+    with op.batch_alter_table("access_roles") as batch_op:
         batch_op.drop_column("is_assignable")
         batch_op.drop_column("is_builtin")
         batch_op.drop_column("description")
 
-    with op.batch_alter_table("groups") as batch_op:
+    with op.batch_alter_table("access_groups") as batch_op:
         batch_op.drop_column("is_active")
         batch_op.drop_column("description")
 
-    with op.batch_alter_table("tenants") as batch_op:
+    with op.batch_alter_table("tenancy_tenants") as batch_op:
         batch_op.drop_column("settings")
         batch_op.drop_column("default_locale")
         batch_op.drop_column("description")
 
-    op.drop_index(op.f("ix_accounts_normalized_email"), table_name="accounts")
-    op.drop_table("accounts")
+    op.drop_index(op.f("ix_access_accounts_normalized_email"), table_name="access_accounts")
+    op.drop_table("access_accounts")

alembic/dev_versions/9d0e1f2a3b4c_system_governance_templates.py

@@ -28,7 +28,7 @@ def upgrade() -> None:
     tables = set(inspector.get_table_names())
 
     # Reconcile only the empty create_all shape for the newly introduced tables.
-    for table_name in ("governance_template_assignments", "governance_templates", "system_settings"):
+    for table_name in ("admin_governance_template_assignments", "admin_governance_templates", "core_system_settings"):
         if table_name in tables:
             count = bind.execute(sa.text(f"SELECT COUNT(*) FROM {table_name}")).scalar_one()
             if count:
@@ -36,7 +36,7 @@ def upgrade() -> None:
             op.drop_table(table_name)
 
     op.create_table(
-        "system_settings",
+        "core_system_settings",
         sa.Column("id", sa.String(length=36), nullable=False),
         sa.Column("default_locale", sa.String(length=20), nullable=False, server_default="en"),
         sa.Column("allow_tenant_custom_groups", sa.Boolean(), nullable=False, server_default=sa.true()),
@@ -50,16 +50,23 @@ def upgrade() -> None:
     now = _now()
     bind.execute(sa.text(
         """
-        INSERT INTO system_settings
+        INSERT INTO core_system_settings
             (id, default_locale, allow_tenant_custom_groups, allow_tenant_custom_roles,
              allow_tenant_api_keys, settings, created_at, updated_at)
         VALUES
-            ('global', 'en', 1, 1, 1, '{}', :created_at, :updated_at)
+            ('global', 'en', :allow_tenant_custom_groups, :allow_tenant_custom_roles,
+             :allow_tenant_api_keys, '{}', :created_at, :updated_at)
         """
-    ), {"created_at": now, "updated_at": now})
+    ), {
+        "allow_tenant_custom_groups": True,
+        "allow_tenant_custom_roles": True,
+        "allow_tenant_api_keys": True,
+        "created_at": now,
+        "updated_at": now,
+    })
 
     op.create_table(
-        "governance_templates",
+        "admin_governance_templates",
         sa.Column("id", sa.String(length=36), nullable=False),
         sa.Column("kind", sa.String(length=20), nullable=False),
         sa.Column("slug", sa.String(length=100), nullable=False),
@@ -72,51 +79,51 @@ def upgrade() -> None:
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("kind", "slug", name="uq_governance_templates_kind_slug"),
     )
-    op.create_index(op.f("ix_governance_templates_kind"), "governance_templates", ["kind"])
+    op.create_index(op.f("ix_admin_governance_templates_kind"), "admin_governance_templates", ["kind"])
 
     op.create_table(
-        "governance_template_assignments",
+        "admin_governance_template_assignments",
         sa.Column("id", sa.String(length=36), nullable=False),
         sa.Column("template_id", sa.String(length=36), nullable=False),
         sa.Column("tenant_id", sa.String(length=36), nullable=False),
         sa.Column("mode", sa.String(length=20), nullable=False, server_default="available"),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
         sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["template_id"], ["governance_templates.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["template_id"], ["admin_governance_templates.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
         sa.PrimaryKeyConstraint("id"),
         sa.UniqueConstraint("template_id", "tenant_id", name="uq_governance_template_tenant"),
     )
-    op.create_index(op.f("ix_governance_template_assignments_template_id"), "governance_template_assignments", ["template_id"])
-    op.create_index(op.f("ix_governance_template_assignments_tenant_id"), "governance_template_assignments", ["tenant_id"])
+    op.create_index(op.f("ix_admin_governance_template_assignments_template_id"), "admin_governance_template_assignments", ["template_id"])
+    op.create_index(op.f("ix_admin_governance_template_assignments_tenant_id"), "admin_governance_template_assignments", ["tenant_id"])
 
-    with op.batch_alter_table("tenants") as batch_op:
+    with op.batch_alter_table("tenancy_tenants") as batch_op:
         batch_op.add_column(sa.Column("allow_custom_groups", sa.Boolean(), nullable=True))
         batch_op.add_column(sa.Column("allow_custom_roles", sa.Boolean(), nullable=True))
         batch_op.add_column(sa.Column("allow_api_keys", sa.Boolean(), nullable=True))
 
-    with op.batch_alter_table("groups") as batch_op:
+    with op.batch_alter_table("access_groups") as batch_op:
         batch_op.add_column(sa.Column("system_template_id", sa.String(length=36), nullable=True))
         batch_op.add_column(sa.Column("system_required", sa.Boolean(), nullable=False, server_default=sa.false()))
         batch_op.create_foreign_key(
             "fk_groups_system_template_id_governance_templates",
-            "governance_templates", ["system_template_id"], ["id"], ondelete="SET NULL",
+            "admin_governance_templates", ["system_template_id"], ["id"], ondelete="SET NULL",
         )
-    op.create_index(op.f("ix_groups_system_template_id"), "groups", ["system_template_id"])
+    op.create_index(op.f("ix_access_groups_system_template_id"), "access_groups", ["system_template_id"])
 
-    with op.batch_alter_table("roles") as batch_op:
+    with op.batch_alter_table("access_roles") as batch_op:
         batch_op.add_column(sa.Column("system_template_id", sa.String(length=36), nullable=True))
         batch_op.add_column(sa.Column("system_required", sa.Boolean(), nullable=False, server_default=sa.false()))
         batch_op.create_foreign_key(
             "fk_roles_system_template_id_governance_templates",
-            "governance_templates", ["system_template_id"], ["id"], ondelete="SET NULL",
+            "admin_governance_templates", ["system_template_id"], ["id"], ondelete="SET NULL",
         )
-    op.create_index(op.f("ix_roles_system_template_id"), "roles", ["system_template_id"])
+    op.create_index(op.f("ix_access_roles_system_template_id"), "access_roles", ["system_template_id"])
 
     # Existing system owners use system:* and need no data change. Extend the
     # read-only built-in auditor role to the newly introduced read scopes.
     auditor = bind.execute(sa.text(
-        "SELECT id, permissions FROM roles WHERE tenant_id IS NULL AND slug = 'system_auditor'"
+        "SELECT id, permissions FROM access_roles WHERE tenant_id IS NULL AND slug = 'system_auditor'"
     )).mappings().first()
     if auditor:
         raw_permissions = auditor["permissions"] or []
@@ -125,7 +132,7 @@ def upgrade() -> None:
             if scope not in permissions:
                 permissions.append(scope)
         roles_table = sa.table(
-            "roles",
+            "access_roles",
             sa.column("id", sa.String),
             sa.column("permissions", sa.JSON),
             sa.column("updated_at", sa.DateTime(timezone=True)),
@@ -138,26 +145,26 @@ def upgrade() -> None:
 
 
 def downgrade() -> None:
-    op.drop_index(op.f("ix_roles_system_template_id"), table_name="roles")
-    with op.batch_alter_table("roles") as batch_op:
+    op.drop_index(op.f("ix_access_roles_system_template_id"), table_name="access_roles")
+    with op.batch_alter_table("access_roles") as batch_op:
         batch_op.drop_constraint("fk_roles_system_template_id_governance_templates", type_="foreignkey")
         batch_op.drop_column("system_required")
         batch_op.drop_column("system_template_id")
 
-    op.drop_index(op.f("ix_groups_system_template_id"), table_name="groups")
-    with op.batch_alter_table("groups") as batch_op:
+    op.drop_index(op.f("ix_access_groups_system_template_id"), table_name="access_groups")
+    with op.batch_alter_table("access_groups") as batch_op:
         batch_op.drop_constraint("fk_groups_system_template_id_governance_templates", type_="foreignkey")
         batch_op.drop_column("system_required")
         batch_op.drop_column("system_template_id")
 
-    with op.batch_alter_table("tenants") as batch_op:
+    with op.batch_alter_table("tenancy_tenants") as batch_op:
         batch_op.drop_column("allow_api_keys")
         batch_op.drop_column("allow_custom_roles")
         batch_op.drop_column("allow_custom_groups")
 
-    op.drop_index(op.f("ix_governance_template_assignments_tenant_id"), table_name="governance_template_assignments")
-    op.drop_index(op.f("ix_governance_template_assignments_template_id"), table_name="governance_template_assignments")
-    op.drop_table("governance_template_assignments")
-    op.drop_index(op.f("ix_governance_templates_kind"), table_name="governance_templates")
-    op.drop_table("governance_templates")
-    op.drop_table("system_settings")
+    op.drop_index(op.f("ix_admin_governance_template_assignments_tenant_id"), table_name="admin_governance_template_assignments")
+    op.drop_index(op.f("ix_admin_governance_template_assignments_template_id"), table_name="admin_governance_template_assignments")
+    op.drop_table("admin_governance_template_assignments")
+    op.drop_index(op.f("ix_admin_governance_templates_kind"), table_name="admin_governance_templates")
+    op.drop_table("admin_governance_templates")
+    op.drop_table("core_system_settings")

alembic/dev_versions/a0b1c2d3e4f5_permission_catalogue_refinement.py

@@ -148,9 +148,9 @@ def upgrade() -> None:
             sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
             sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
             sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-            sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
+            sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
             sa.ForeignKeyConstraint(["campaign_id"], ["campaigns.id"], ondelete="CASCADE"),
-            sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
+            sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
             sa.PrimaryKeyConstraint("id"),
             sa.UniqueConstraint("campaign_id", "target_type", "target_id", name="uq_campaign_share_target"),
         )
@@ -160,32 +160,32 @@ def upgrade() -> None:
         op.create_index("ix_campaign_shares_target_id", "campaign_shares", ["target_id"])
         op.create_index("ix_campaign_shares_created_by_user_id", "campaign_shares", ["created_by_user_id"])
         op.create_index("ix_campaign_shares_revoked_at", "campaign_shares", ["revoked_at"])
-    if "roles" not in tables:
+    if "access_roles" not in tables:
         return
 
-    rows = bind.execute(sa.text("SELECT id, permissions FROM roles")).mappings().all()
+    rows = bind.execute(sa.text("SELECT id, permissions FROM access_roles")).mappings().all()
     for row in rows:
         bind.execute(
-            sa.text("UPDATE roles SET permissions = :permissions WHERE id = :id"),
+            sa.text("UPDATE access_roles SET permissions = :permissions WHERE id = :id"),
             {"id": row["id"], "permissions": _json(_expand_legacy(_decode(row["permissions"])))},
         )
 
     for slug, permissions in TENANT_ROLE_PERMISSIONS.items():
         bind.execute(
-            sa.text("UPDATE roles SET permissions = :permissions WHERE tenant_id IS NOT NULL AND slug = :slug AND is_builtin = TRUE"),
+            sa.text("UPDATE access_roles SET permissions = :permissions WHERE tenant_id IS NOT NULL AND slug = :slug AND is_builtin = TRUE"),
             {"slug": slug, "permissions": _json(permissions)},
         )
 
     now = datetime.now(timezone.utc)
     for slug, permissions in SYSTEM_ROLE_PERMISSIONS.items():
         existing = bind.execute(
-            sa.text("SELECT id FROM roles WHERE tenant_id IS NULL AND slug = :slug"), {"slug": slug}
+            sa.text("SELECT id FROM access_roles WHERE tenant_id IS NULL AND slug = :slug"), {"slug": slug}
         ).first()
         is_protected = slug == "system_owner"
         if existing:
             bind.execute(
                 sa.text(
-                    "UPDATE roles SET permissions = :permissions, is_builtin = :is_builtin, is_assignable = TRUE "
+                    "UPDATE access_roles SET permissions = :permissions, is_builtin = :is_builtin, is_assignable = TRUE "
                     "WHERE tenant_id IS NULL AND slug = :slug"
                 ),
                 {"slug": slug, "permissions": _json(permissions), "is_builtin": is_protected},
@@ -199,7 +199,7 @@ def upgrade() -> None:
             name, description = names[slug]
             bind.execute(
                 sa.text(
-                    "INSERT INTO roles (id, tenant_id, slug, name, description, permissions, is_builtin, is_assignable, "
+                    "INSERT INTO access_roles (id, tenant_id, slug, name, description, permissions, is_builtin, is_assignable, "
                     "system_template_id, system_required, created_at, updated_at) "
                     "VALUES (:id, NULL, :slug, :name, :description, :permissions, :is_builtin, TRUE, NULL, FALSE, :created_at, :updated_at)"
                 ),

alembic/dev_versions/b57c5b216bce_initial_persistence_models.py

@@ -18,7 +18,7 @@ depends_on = None
 
 def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    op.create_table('tenants',
+    op.create_table('tenancy_tenants',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('slug', sa.String(length=100), nullable=False),
     sa.Column('name', sa.String(length=255), nullable=False),
@@ -27,7 +27,7 @@ def upgrade() -> None:
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_tenants'))
     )
-    op.create_index(op.f('ix_tenants_slug'), 'tenants', ['slug'], unique=True)
+    op.create_index(op.f('ix_tenancy_tenants_slug'), 'tenancy_tenants', ['slug'], unique=True)
     op.create_table('attachment_blobs',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=False),
@@ -38,25 +38,25 @@ def upgrade() -> None:
     sa.Column('storage_key', sa.String(length=1000), nullable=False),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_attachment_blobs_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_attachment_blobs_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_attachment_blobs')),
     sa.UniqueConstraint('tenant_id', 'sha256', name='uq_attachment_blobs_tenant_sha256')
     )
     op.create_index(op.f('ix_attachment_blobs_sha256'), 'attachment_blobs', ['sha256'], unique=False)
     op.create_index(op.f('ix_attachment_blobs_tenant_id'), 'attachment_blobs', ['tenant_id'], unique=False)
-    op.create_table('groups',
+    op.create_table('access_groups',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=False),
     sa.Column('slug', sa.String(length=100), nullable=False),
     sa.Column('name', sa.String(length=255), nullable=False),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_groups_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_groups_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_groups')),
     sa.UniqueConstraint('tenant_id', 'slug', name='uq_groups_tenant_slug')
     )
-    op.create_index(op.f('ix_groups_tenant_id'), 'groups', ['tenant_id'], unique=False)
-    op.create_table('roles',
+    op.create_index(op.f('ix_access_groups_tenant_id'), 'access_groups', ['tenant_id'], unique=False)
+    op.create_table('access_roles',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=True),
     sa.Column('slug', sa.String(length=100), nullable=False),
@@ -64,12 +64,12 @@ def upgrade() -> None:
     sa.Column('permissions', sa.JSON(), nullable=False),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_roles_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_roles_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_roles')),
     sa.UniqueConstraint('tenant_id', 'slug', name='uq_roles_tenant_slug')
     )
-    op.create_index(op.f('ix_roles_tenant_id'), 'roles', ['tenant_id'], unique=False)
-    op.create_table('users',
+    op.create_index(op.f('ix_access_roles_tenant_id'), 'access_roles', ['tenant_id'], unique=False)
+    op.create_table('access_users',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=False),
     sa.Column('email', sa.String(length=320), nullable=False),
@@ -78,13 +78,13 @@ def upgrade() -> None:
     sa.Column('is_tenant_admin', sa.Boolean(), nullable=False),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_users_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_users_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_users')),
     sa.UniqueConstraint('tenant_id', 'email', name='uq_users_tenant_email')
     )
-    op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=False)
-    op.create_index(op.f('ix_users_tenant_id'), 'users', ['tenant_id'], unique=False)
-    op.create_table('api_keys',
+    op.create_index(op.f('ix_access_users_email'), 'access_users', ['email'], unique=False)
+    op.create_index(op.f('ix_access_users_tenant_id'), 'access_users', ['tenant_id'], unique=False)
+    op.create_table('access_api_keys',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=False),
     sa.Column('user_id', sa.String(length=36), nullable=False),
@@ -97,13 +97,13 @@ def upgrade() -> None:
     sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_api_keys_tenant_id_tenants'), ondelete='CASCADE'),
-    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_api_keys_user_id_users'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_api_keys_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_api_keys_user_id_users'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_api_keys'))
     )
-    op.create_index(op.f('ix_api_keys_prefix'), 'api_keys', ['prefix'], unique=False)
-    op.create_index(op.f('ix_api_keys_tenant_id'), 'api_keys', ['tenant_id'], unique=False)
-    op.create_index(op.f('ix_api_keys_user_id'), 'api_keys', ['user_id'], unique=False)
+    op.create_index(op.f('ix_access_api_keys_prefix'), 'access_api_keys', ['prefix'], unique=False)
+    op.create_index(op.f('ix_access_api_keys_tenant_id'), 'access_api_keys', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_access_api_keys_user_id'), 'access_api_keys', ['user_id'], unique=False)
     op.create_table('campaigns',
     sa.Column('id', sa.String(length=36), nullable=False),
     sa.Column('tenant_id', sa.String(length=36), nullable=False),
@@ -115,8 +115,8 @@ def upgrade() -> None:
     sa.Column('current_version_id', sa.String(length=36), nullable=True),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['created_by_user_id'], ['users.id'], name=op.f('fk_campaigns_created_by_user_id_users'), ondelete='SET NULL'),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_campaigns_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_campaigns_created_by_user_id_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_campaigns_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_campaigns')),
     sa.UniqueConstraint('tenant_id', 'external_id', name='uq_campaigns_tenant_external_id')
     )
@@ -138,8 +138,8 @@ def upgrade() -> None:
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
     sa.ForeignKeyConstraint(['blob_id'], ['attachment_blobs.id'], name=op.f('fk_attachment_instances_blob_id_attachment_blobs'), ondelete='CASCADE'),
     sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_attachment_instances_campaign_id_campaigns'), ondelete='CASCADE'),
-    sa.ForeignKeyConstraint(['owner_user_id'], ['users.id'], name=op.f('fk_attachment_instances_owner_user_id_users'), ondelete='SET NULL'),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_attachment_instances_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['access_users.id'], name=op.f('fk_attachment_instances_owner_user_id_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_attachment_instances_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_attachment_instances'))
     )
     op.create_index(op.f('ix_attachment_instances_blob_id'), 'attachment_instances', ['blob_id'], unique=False)
@@ -157,9 +157,9 @@ def upgrade() -> None:
     sa.Column('details', sa.JSON(), nullable=True),
     sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.ForeignKeyConstraint(['api_key_id'], ['api_keys.id'], name=op.f('fk_audit_log_api_key_id_api_keys'), ondelete='SET NULL'),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_audit_log_tenant_id_tenants'), ondelete='CASCADE'),
-    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_audit_log_user_id_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['api_key_id'], ['access_api_keys.id'], name=op.f('fk_audit_log_api_key_id_api_keys'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_audit_log_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_audit_log_user_id_users'), ondelete='SET NULL'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_audit_log'))
     )
     op.create_index(op.f('ix_audit_log_action'), 'audit_log', ['action'], unique=False)
@@ -213,7 +213,7 @@ def upgrade() -> None:
     sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
     sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_jobs_campaign_id_campaigns'), ondelete='CASCADE'),
     sa.ForeignKeyConstraint(['campaign_version_id'], ['campaign_versions.id'], name=op.f('fk_campaign_jobs_campaign_version_id_campaign_versions'), ondelete='CASCADE'),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_campaign_jobs_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_campaign_jobs_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_jobs')),
     sa.UniqueConstraint('campaign_version_id', 'entry_index', name='uq_campaign_jobs_version_entry')
     )
@@ -243,7 +243,7 @@ def upgrade() -> None:
     sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_issues_campaign_id_campaigns'), ondelete='CASCADE'),
     sa.ForeignKeyConstraint(['campaign_version_id'], ['campaign_versions.id'], name=op.f('fk_campaign_issues_campaign_version_id_campaign_versions'), ondelete='CASCADE'),
     sa.ForeignKeyConstraint(['job_id'], ['campaign_jobs.id'], name=op.f('fk_campaign_issues_job_id_campaign_jobs'), ondelete='CASCADE'),
-    sa.ForeignKeyConstraint(['tenant_id'], ['tenants.id'], name=op.f('fk_campaign_issues_tenant_id_tenants'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tenant_id'], ['tenancy_tenants.id'], name=op.f('fk_campaign_issues_tenant_id_tenants'), ondelete='CASCADE'),
     sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_issues'))
     )
     op.create_index(op.f('ix_campaign_issues_campaign_id'), 'campaign_issues', ['campaign_id'], unique=False)
@@ -327,20 +327,20 @@ def downgrade() -> None:
     op.drop_index(op.f('ix_campaigns_external_id'), table_name='campaigns')
     op.drop_index(op.f('ix_campaigns_created_by_user_id'), table_name='campaigns')
     op.drop_table('campaigns')
-    op.drop_index(op.f('ix_api_keys_user_id'), table_name='api_keys')
-    op.drop_index(op.f('ix_api_keys_tenant_id'), table_name='api_keys')
-    op.drop_index(op.f('ix_api_keys_prefix'), table_name='api_keys')
-    op.drop_table('api_keys')
-    op.drop_index(op.f('ix_users_tenant_id'), table_name='users')
-    op.drop_index(op.f('ix_users_email'), table_name='users')
-    op.drop_table('users')
-    op.drop_index(op.f('ix_roles_tenant_id'), table_name='roles')
-    op.drop_table('roles')
-    op.drop_index(op.f('ix_groups_tenant_id'), table_name='groups')
-    op.drop_table('groups')
+    op.drop_index(op.f('ix_access_api_keys_user_id'), table_name='access_api_keys')
+    op.drop_index(op.f('ix_access_api_keys_tenant_id'), table_name='access_api_keys')
+    op.drop_index(op.f('ix_access_api_keys_prefix'), table_name='access_api_keys')
+    op.drop_table('access_api_keys')
+    op.drop_index(op.f('ix_access_users_tenant_id'), table_name='access_users')
+    op.drop_index(op.f('ix_access_users_email'), table_name='access_users')
+    op.drop_table('access_users')
+    op.drop_index(op.f('ix_access_roles_tenant_id'), table_name='access_roles')
+    op.drop_table('access_roles')
+    op.drop_index(op.f('ix_access_groups_tenant_id'), table_name='access_groups')
+    op.drop_table('access_groups')
     op.drop_index(op.f('ix_attachment_blobs_tenant_id'), table_name='attachment_blobs')
     op.drop_index(op.f('ix_attachment_blobs_sha256'), table_name='attachment_blobs')
     op.drop_table('attachment_blobs')
-    op.drop_index(op.f('ix_tenants_slug'), table_name='tenants')
-    op.drop_table('tenants')
+    op.drop_index(op.f('ix_tenancy_tenants_slug'), table_name='tenancy_tenants')
+    op.drop_table('tenancy_tenants')
     # ### end Alembic commands ###

alembic/dev_versions/d3e4f5a6b7c8_mail_profiles_and_cookie_csrf.py

@@ -19,10 +19,10 @@ def upgrade() -> None:
     bind = op.get_bind()
     inspector = sa.inspect(bind)
     tables = set(inspector.get_table_names())
-    if "auth_sessions" in tables:
-        columns = {column["name"] for column in inspector.get_columns("auth_sessions")}
+    if "access_auth_sessions" in tables:
+        columns = {column["name"] for column in inspector.get_columns("access_auth_sessions")}
         if "csrf_token_hash" not in columns:
-            op.add_column("auth_sessions", sa.Column("csrf_token_hash", sa.String(length=128), nullable=True))
+            op.add_column("access_auth_sessions", sa.Column("csrf_token_hash", sa.String(length=128), nullable=True))
     if "mail_server_profiles" not in tables:
         op.create_table(
             "mail_server_profiles",
@@ -40,9 +40,9 @@ def upgrade() -> None:
             sa.Column("updated_by_user_id", sa.String(length=36), nullable=True),
             sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
             sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-            sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
-            sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
-            sa.ForeignKeyConstraint(["updated_by_user_id"], ["users.id"], ondelete="SET NULL"),
+            sa.ForeignKeyConstraint(["created_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
+            sa.ForeignKeyConstraint(["tenant_id"], ["tenancy_tenants.id"], ondelete="CASCADE"),
+            sa.ForeignKeyConstraint(["updated_by_user_id"], ["access_users.id"], ondelete="SET NULL"),
             sa.PrimaryKeyConstraint("id"),
             sa.UniqueConstraint("tenant_id", "slug", name="uq_mail_server_profiles_tenant_slug"),
         )
@@ -67,7 +67,7 @@ def downgrade() -> None:
             except Exception:
                 pass
         op.drop_table("mail_server_profiles")
-    if "auth_sessions" in inspector.get_table_names():
-        columns = {column["name"] for column in inspector.get_columns("auth_sessions")}
+    if "access_auth_sessions" in inspector.get_table_names():
+        columns = {column["name"] for column in inspector.get_columns("access_auth_sessions")}
         if "csrf_token_hash" in columns:
-            op.drop_column("auth_sessions", "csrf_token_hash")
+            op.drop_column("access_auth_sessions", "csrf_token_hash")

alembic/dev_versions/e4f5a6b7c8d9_mail_profile_policy_hierarchy.py

@@ -31,7 +31,7 @@ def upgrade() -> None:
     inspector = sa.inspect(bind)
     tables = set(inspector.get_table_names())
 
-    for table_name in ("users", "groups", "campaigns"):
+    for table_name in ("access_users", "access_groups", "campaigns"):
         if table_name not in tables:
             continue
         columns = _columns(inspector, table_name)
@@ -83,6 +83,6 @@ def downgrade() -> None:
                 batch.drop_column("scope_type")
             batch.alter_column("tenant_id", existing_type=sa.String(length=36), nullable=False)
 
-    for table_name in ("campaigns", "groups", "users"):
+    for table_name in ("campaigns", "access_groups", "access_users"):
         if table_name in tables and "mail_profile_policy" in _columns(inspector, table_name):
             op.drop_column(table_name, "mail_profile_policy")

alembic/dev_versions/f5a6b7c8d9e0_hierarchical_settings.py

@@ -25,7 +25,7 @@ def upgrade() -> None:
     bind = op.get_bind()
     inspector = sa.inspect(bind)
     tables = set(inspector.get_table_names())
-    for table_name in ("users", "groups", "campaigns"):
+    for table_name in ("access_users", "access_groups", "campaigns"):
         if table_name not in tables:
             continue
         if "settings" not in _columns(inspector, table_name):
@@ -36,6 +36,6 @@ def downgrade() -> None:
     bind = op.get_bind()
     inspector = sa.inspect(bind)
     tables = set(inspector.get_table_names())
-    for table_name in ("campaigns", "groups", "users"):
+    for table_name in ("campaigns", "access_groups", "access_users"):
         if table_name in tables and "settings" in _columns(inspector, table_name):
             op.drop_column(table_name, "settings")

alembic/env.py

@@ -5,13 +5,15 @@ from logging.config import fileConfig
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 
-from govoplan_core.access.db import models as access_models  # noqa: F401 - populate access metadata
+from govoplan_access.backend.db import models as access_models  # noqa: F401 - populate access metadata
+from govoplan_core.admin import models as core_admin_models  # noqa: F401 - populate core admin metadata
+from govoplan_core.core import change_sequence as core_change_sequence_models  # noqa: F401 - populate core metadata
 from govoplan_core.core.migrations import migration_metadata_plan
 from govoplan_core.db.base import Base
-from govoplan_core.db import models  # noqa: F401 - populate core metadata
 from govoplan_core.server.default_config import get_server_config
 from govoplan_core.server.registry import build_platform_registry
 from govoplan_core.settings import settings
+from govoplan_core.tenancy.scope import scope_registry
 
 config = context.config
 database_url = config.attributes.get("database_url") or settings.database_url
@@ -23,11 +25,13 @@ if config.config_file_name is not None:
 
 def _target_metadata():
     server_config = get_server_config()
+    enabled_modules = config.attributes.get("enabled_modules", server_config.enabled_modules)
+    manifest_factories = config.attributes.get("manifest_factories", server_config.manifest_factories)
     registry = build_platform_registry(
-        server_config.enabled_modules,
-        manifest_factories=server_config.manifest_factories,
+        enabled_modules,
+        manifest_factories=manifest_factories,
     )
-    plan = migration_metadata_plan(registry, extra_metadata=(Base.metadata,))
+    plan = migration_metadata_plan(registry, extra_metadata=(scope_registry.metadata, Base.metadata))
     return tuple(dict.fromkeys(plan.metadata))
 
 

alembic/versions/2c3d4e5f6a7b_auth_sessions_and_rbac.py

@@ -1,130 +0,0 @@
-"""auth sessions and RBAC assignments
-
-Revision ID: 2c3d4e5f6a7b
-Revises: 1f8d4c2a0b7e
-Create Date: 2026-06-08 10:00:00.000000
-"""
-from __future__ import annotations
-
-from alembic import op
-import sqlalchemy as sa
-
-
-revision = "2c3d4e5f6a7b"
-down_revision = "1f8d4c2a0b7e"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    with op.batch_alter_table("users") as batch_op:
-        batch_op.add_column(sa.Column("auth_provider", sa.String(length=50), nullable=False, server_default="local"))
-        batch_op.add_column(sa.Column("password_hash", sa.String(length=500), nullable=True))
-        batch_op.add_column(sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True))
-
-    op.create_table(
-        "user_group_memberships",
-        sa.Column("id", sa.String(length=36), nullable=False),
-        sa.Column("tenant_id", sa.String(length=36), nullable=False),
-        sa.Column("user_id", sa.String(length=36), nullable=False),
-        sa.Column("group_id", sa.String(length=36), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["group_id"], ["groups.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("tenant_id", "user_id", "group_id", name="uq_user_group_memberships"),
-    )
-    op.create_index(op.f("ix_user_group_memberships_tenant_id"), "user_group_memberships", ["tenant_id"])
-    op.create_index(op.f("ix_user_group_memberships_user_id"), "user_group_memberships", ["user_id"])
-    op.create_index(op.f("ix_user_group_memberships_group_id"), "user_group_memberships", ["group_id"])
-
-    op.create_table(
-        "user_role_assignments",
-        sa.Column("id", sa.String(length=36), nullable=False),
-        sa.Column("tenant_id", sa.String(length=36), nullable=False),
-        sa.Column("user_id", sa.String(length=36), nullable=False),
-        sa.Column("role_id", sa.String(length=36), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["role_id"], ["roles.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("tenant_id", "user_id", "role_id", name="uq_user_role_assignments"),
-    )
-    op.create_index(op.f("ix_user_role_assignments_tenant_id"), "user_role_assignments", ["tenant_id"])
-    op.create_index(op.f("ix_user_role_assignments_user_id"), "user_role_assignments", ["user_id"])
-    op.create_index(op.f("ix_user_role_assignments_role_id"), "user_role_assignments", ["role_id"])
-
-    op.create_table(
-        "group_role_assignments",
-        sa.Column("id", sa.String(length=36), nullable=False),
-        sa.Column("tenant_id", sa.String(length=36), nullable=False),
-        sa.Column("group_id", sa.String(length=36), nullable=False),
-        sa.Column("role_id", sa.String(length=36), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["group_id"], ["groups.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["role_id"], ["roles.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("tenant_id", "group_id", "role_id", name="uq_group_role_assignments"),
-    )
-    op.create_index(op.f("ix_group_role_assignments_tenant_id"), "group_role_assignments", ["tenant_id"])
-    op.create_index(op.f("ix_group_role_assignments_group_id"), "group_role_assignments", ["group_id"])
-    op.create_index(op.f("ix_group_role_assignments_role_id"), "group_role_assignments", ["role_id"])
-
-    op.create_table(
-        "auth_sessions",
-        sa.Column("id", sa.String(length=36), nullable=False),
-        sa.Column("tenant_id", sa.String(length=36), nullable=False),
-        sa.Column("user_id", sa.String(length=36), nullable=False),
-        sa.Column("token_hash", sa.String(length=128), nullable=False),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("user_agent", sa.String(length=500), nullable=True),
-        sa.Column("ip_address", sa.String(length=100), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.ForeignKeyConstraint(["tenant_id"], ["tenants.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("token_hash"),
-    )
-    op.create_index(op.f("ix_auth_sessions_tenant_id"), "auth_sessions", ["tenant_id"])
-    op.create_index(op.f("ix_auth_sessions_user_id"), "auth_sessions", ["user_id"])
-    op.create_index(op.f("ix_auth_sessions_token_hash"), "auth_sessions", ["token_hash"])
-    op.create_index(op.f("ix_auth_sessions_expires_at"), "auth_sessions", ["expires_at"])
-    op.create_index(op.f("ix_auth_sessions_revoked_at"), "auth_sessions", ["revoked_at"])
-
-
-def downgrade() -> None:
-    op.drop_index(op.f("ix_auth_sessions_revoked_at"), table_name="auth_sessions")
-    op.drop_index(op.f("ix_auth_sessions_expires_at"), table_name="auth_sessions")
-    op.drop_index(op.f("ix_auth_sessions_token_hash"), table_name="auth_sessions")
-    op.drop_index(op.f("ix_auth_sessions_user_id"), table_name="auth_sessions")
-    op.drop_index(op.f("ix_auth_sessions_tenant_id"), table_name="auth_sessions")
-    op.drop_table("auth_sessions")
-
-    op.drop_index(op.f("ix_group_role_assignments_role_id"), table_name="group_role_assignments")
-    op.drop_index(op.f("ix_group_role_assignments_group_id"), table_name="group_role_assignments")
-    op.drop_index(op.f("ix_group_role_assignments_tenant_id"), table_name="group_role_assignments")
-    op.drop_table("group_role_assignments")
-
-    op.drop_index(op.f("ix_user_role_assignments_role_id"), table_name="user_role_assignments")
-    op.drop_index(op.f("ix_user_role_assignments_user_id"), table_name="user_role_assignments")
-    op.drop_index(op.f("ix_user_role_assignments_tenant_id"), table_name="user_role_assignments")
-    op.drop_table("user_role_assignments")
-
-    op.drop_index(op.f("ix_user_group_memberships_group_id"), table_name="user_group_memberships")
-    op.drop_index(op.f("ix_user_group_memberships_user_id"), table_name="user_group_memberships")
-    op.drop_index(op.f("ix_user_group_memberships_tenant_id"), table_name="user_group_memberships")
-    op.drop_table("user_group_memberships")
-
-    with op.batch_alter_table("users") as batch_op:
-        batch_op.drop_column("last_login_at")
-        batch_op.drop_column("password_hash")
-        batch_op.drop_column("auth_provider")

alembic/versions/4f2a9c8e7b6d_v017_core_baseline.py

@@ -0,0 +1,892 @@
+"""v0.1.7 core baseline
+
+Revision ID: 4f2a9c8e7b6d
+Revises: None
+Create Date: 2026-07-11 00:00:00.000000
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '4f2a9c8e7b6d'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _seed_core_defaults() -> None:
+    bind = op.get_bind()
+    now = _now()
+    if not bind.execute(sa.text("SELECT 1 FROM core_system_settings WHERE id = 'global'")).first():
+        settings_table = sa.table(
+            "core_system_settings",
+            sa.column("id", sa.String),
+            sa.column("default_locale", sa.String),
+            sa.column("allow_tenant_custom_groups", sa.Boolean),
+            sa.column("allow_tenant_custom_roles", sa.Boolean),
+            sa.column("allow_tenant_api_keys", sa.Boolean),
+            sa.column("settings", sa.JSON),
+            sa.column("created_at", sa.DateTime(timezone=True)),
+            sa.column("updated_at", sa.DateTime(timezone=True)),
+        )
+        bind.execute(
+            settings_table.insert().values({
+                "id": "global",
+                "default_locale": "en",
+                "allow_tenant_custom_groups": True,
+                "allow_tenant_custom_roles": True,
+                "allow_tenant_api_keys": True,
+                "settings": {},
+                "created_at": now,
+                "updated_at": now,
+            }),
+        )
+    system_roles = {
+        "system_owner": {
+            "name": "System owner",
+            "description": "Protected full instance-wide administration.",
+            "permissions": ["system:*"],
+            "is_builtin": True,
+        },
+        "system_admin": {
+            "name": "System administrator",
+            "description": "Manage the instance without granting the protected System owner role.",
+            "permissions": [
+                "system:tenants:read", "system:tenants:create", "system:tenants:update", "system:tenants:suspend",
+                "system:accounts:read", "system:accounts:create", "system:accounts:update", "system:accounts:suspend",
+                "system:roles:read", "system:roles:write", "system:roles:assign", "system:access:read", "system:access:assign",
+                "system:audit:read", "system:settings:read", "system:settings:write", "system:governance:read", "system:governance:write",
+            ],
+            "is_builtin": False,
+        },
+        "system_auditor": {
+            "name": "System auditor",
+            "description": "Read-only access to system administration and audit.",
+            "permissions": [
+                "system:tenants:read", "system:accounts:read", "system:roles:read", "system:access:read",
+                "system:audit:read", "system:settings:read", "system:governance:read",
+            ],
+            "is_builtin": False,
+        },
+    }
+    roles_table = sa.table(
+        "access_roles",
+        sa.column("id", sa.String),
+        sa.column("tenant_id", sa.String),
+        sa.column("slug", sa.String),
+        sa.column("name", sa.String),
+        sa.column("description", sa.Text),
+        sa.column("permissions", sa.JSON),
+        sa.column("is_builtin", sa.Boolean),
+        sa.column("is_assignable", sa.Boolean),
+        sa.column("system_template_id", sa.String),
+        sa.column("system_required", sa.Boolean),
+        sa.column("created_at", sa.DateTime(timezone=True)),
+        sa.column("updated_at", sa.DateTime(timezone=True)),
+    )
+    for slug, role in system_roles.items():
+        if bind.execute(
+            sa.text("SELECT 1 FROM access_roles WHERE tenant_id IS NULL AND slug = :slug"),
+            {"slug": slug},
+        ).first():
+            continue
+        bind.execute(
+            roles_table.insert().values(
+                id=str(uuid4()),
+                tenant_id=None,
+                slug=slug,
+                name=role["name"],
+                description=role["description"],
+                permissions=role["permissions"],
+                is_builtin=bool(role["is_builtin"]),
+                is_assignable=True,
+                system_template_id=None,
+                system_required=False,
+                created_at=now,
+                updated_at=now,
+            ),
+        )
+
+
+def upgrade() -> None:
+    op.create_table('core_scopes',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('slug', sa.String(length=100), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('default_locale', sa.String(length=20), nullable=False),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('allow_custom_groups', sa.Boolean(), nullable=True),
+    sa.Column('allow_custom_roles', sa.Boolean(), nullable=True),
+    sa.Column('allow_api_keys', sa.Boolean(), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_core_scopes'))
+    )
+    op.create_index(op.f('ix_core_scopes_slug'), 'core_scopes', ['slug'], unique=True)
+    op.create_table('access_accounts',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('email', sa.String(length=320), nullable=False),
+    sa.Column('normalized_email', sa.String(length=320), nullable=False),
+    sa.Column('display_name', sa.String(length=255), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('auth_provider', sa.String(length=50), nullable=False),
+    sa.Column('password_hash', sa.String(length=500), nullable=True),
+    sa.Column('password_reset_required', sa.Boolean(), nullable=False),
+    sa.Column('last_login_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_accounts'))
+    )
+    op.create_index(op.f('ix_access_accounts_normalized_email'), 'access_accounts', ['normalized_email'], unique=True)
+    op.create_table('access_groups',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('slug', sa.String(length=100), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('system_template_id', sa.String(length=36), nullable=True),
+    sa.Column('system_required', sa.Boolean(), nullable=False),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('mail_profile_policy', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_groups')),
+    sa.UniqueConstraint('tenant_id', 'slug', name='uq_groups_tenant_slug')
+    )
+    op.create_index(op.f('ix_access_groups_system_template_id'), 'access_groups', ['system_template_id'], unique=False)
+    op.create_index(op.f('ix_access_groups_tenant_id'), 'access_groups', ['tenant_id'], unique=False)
+    op.create_table('access_roles',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=True),
+    sa.Column('slug', sa.String(length=100), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('permissions', sa.JSON(), nullable=False),
+    sa.Column('is_builtin', sa.Boolean(), nullable=False),
+    sa.Column('is_assignable', sa.Boolean(), nullable=False),
+    sa.Column('system_template_id', sa.String(length=36), nullable=True),
+    sa.Column('system_required', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_roles')),
+    sa.UniqueConstraint('tenant_id', 'slug', name='uq_roles_tenant_slug')
+    )
+    op.create_index(op.f('ix_access_roles_system_template_id'), 'access_roles', ['system_template_id'], unique=False)
+    op.create_index(op.f('ix_access_roles_tenant_id'), 'access_roles', ['tenant_id'], unique=False)
+    op.create_index('uq_roles_system_slug', 'access_roles', ['slug'], unique=True, sqlite_where=sa.text('tenant_id IS NULL'), postgresql_where=sa.text('tenant_id IS NULL'))
+    op.create_table('admin_governance_templates',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('kind', sa.String(length=20), nullable=False),
+    sa.Column('slug', sa.String(length=100), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('permissions', sa.JSON(), nullable=False),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_admin_governance_templates')),
+    sa.UniqueConstraint('kind', 'slug', name='uq_governance_templates_kind_slug')
+    )
+    op.create_index(op.f('ix_admin_governance_templates_kind'), 'admin_governance_templates', ['kind'], unique=False)
+    op.create_table('attachment_blobs',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('sha256', sa.String(length=64), nullable=False),
+    sa.Column('size_bytes', sa.Integer(), nullable=False),
+    sa.Column('mime_type', sa.String(length=255), nullable=True),
+    sa.Column('storage_bucket', sa.String(length=255), nullable=False),
+    sa.Column('storage_key', sa.String(length=1000), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_attachment_blobs')),
+    sa.UniqueConstraint('tenant_id', 'sha256', name='uq_attachment_blobs_tenant_sha256')
+    )
+    op.create_index(op.f('ix_attachment_blobs_sha256'), 'attachment_blobs', ['sha256'], unique=False)
+    op.create_index(op.f('ix_attachment_blobs_tenant_id'), 'attachment_blobs', ['tenant_id'], unique=False)
+    op.create_table('audit_outbox_events',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('event_id', sa.String(length=36), nullable=False),
+    sa.Column('event_type', sa.String(length=200), nullable=False),
+    sa.Column('module_id', sa.String(length=100), nullable=False),
+    sa.Column('correlation_id', sa.String(length=128), nullable=True),
+    sa.Column('causation_id', sa.String(length=128), nullable=True),
+    sa.Column('classification', sa.String(length=40), nullable=False),
+    sa.Column('payload', sa.JSON(), nullable=False),
+    sa.Column('status', sa.String(length=20), nullable=False),
+    sa.Column('attempts', sa.Integer(), nullable=False),
+    sa.Column('next_attempt_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('dispatched_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_audit_outbox_events')),
+    sa.UniqueConstraint('event_id', name='uq_audit_outbox_events_event_id')
+    )
+    op.create_index('ix_audit_outbox_events_correlation_id', 'audit_outbox_events', ['correlation_id'], unique=False)
+    op.create_index('ix_audit_outbox_events_event_type', 'audit_outbox_events', ['event_type'], unique=False)
+    op.create_index(op.f('ix_audit_outbox_events_status'), 'audit_outbox_events', ['status'], unique=False)
+    op.create_index('ix_audit_outbox_events_status_next_attempt_at', 'audit_outbox_events', ['status', 'next_attempt_at'], unique=False)
+    op.create_table('core_change_sequence',
+    sa.Column('id', sa.BigInteger().with_variant(sa.Integer(), 'sqlite'), autoincrement=True, nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=True),
+    sa.Column('module_id', sa.String(length=100), nullable=False),
+    sa.Column('collection', sa.String(length=150), nullable=False),
+    sa.Column('resource_type', sa.String(length=100), nullable=False),
+    sa.Column('resource_id', sa.String(length=255), nullable=False),
+    sa.Column('operation', sa.String(length=30), nullable=False),
+    sa.Column('actor_type', sa.String(length=30), nullable=True),
+    sa.Column('actor_id', sa.String(length=255), nullable=True),
+    sa.Column('payload', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_core_change_sequence'))
+    )
+    op.create_index(op.f('ix_core_change_sequence_actor_id'), 'core_change_sequence', ['actor_id'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_actor_type'), 'core_change_sequence', ['actor_type'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_collection'), 'core_change_sequence', ['collection'], unique=False)
+    op.create_index('ix_core_change_sequence_collection_id', 'core_change_sequence', ['collection', 'id'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_created_at'), 'core_change_sequence', ['created_at'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_module_id'), 'core_change_sequence', ['module_id'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_operation'), 'core_change_sequence', ['operation'], unique=False)
+    op.create_index('ix_core_change_sequence_resource', 'core_change_sequence', ['module_id', 'resource_type', 'resource_id'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_resource_id'), 'core_change_sequence', ['resource_id'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_resource_type'), 'core_change_sequence', ['resource_type'], unique=False)
+    op.create_index(op.f('ix_core_change_sequence_tenant_id'), 'core_change_sequence', ['tenant_id'], unique=False)
+    op.create_index('ix_core_change_sequence_tenant_module_id', 'core_change_sequence', ['tenant_id', 'module_id', 'id'], unique=False)
+    op.create_table('core_change_sequence_retention_floor',
+    sa.Column('id', sa.BigInteger().with_variant(sa.Integer(), 'sqlite'), autoincrement=True, nullable=False),
+    sa.Column('tenant_key', sa.String(length=36), nullable=False),
+    sa.Column('module_id', sa.String(length=100), nullable=False),
+    sa.Column('collection', sa.String(length=150), nullable=False),
+    sa.Column('min_valid_sequence', sa.BigInteger().with_variant(sa.Integer(), 'sqlite'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_core_change_sequence_retention_floor')),
+    sa.UniqueConstraint('tenant_key', 'module_id', 'collection', name='uq_core_change_sequence_retention_scope')
+    )
+    op.create_index('ix_core_change_sequence_retention_scope', 'core_change_sequence_retention_floor', ['tenant_key', 'module_id', 'collection'], unique=False)
+    op.create_table('core_system_settings',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('default_locale', sa.String(length=20), nullable=False),
+    sa.Column('allow_tenant_custom_groups', sa.Boolean(), nullable=False),
+    sa.Column('allow_tenant_custom_roles', sa.Boolean(), nullable=False),
+    sa.Column('allow_tenant_api_keys', sa.Boolean(), nullable=False),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_core_system_settings'))
+    )
+    op.create_table('file_blobs',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('storage_backend', sa.String(length=50), nullable=False),
+    sa.Column('storage_bucket', sa.String(length=255), nullable=True),
+    sa.Column('storage_key', sa.String(length=1000), nullable=False),
+    sa.Column('checksum_sha256', sa.String(length=64), nullable=False),
+    sa.Column('size_bytes', sa.Integer(), nullable=False),
+    sa.Column('content_type', sa.String(length=255), nullable=True),
+    sa.Column('ref_count', sa.Integer(), nullable=False),
+    sa.Column('retained_until', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_blobs')),
+    sa.UniqueConstraint('tenant_id', 'checksum_sha256', 'size_bytes', name='uq_file_blobs_tenant_checksum_size')
+    )
+    op.create_index(op.f('ix_file_blobs_checksum_sha256'), 'file_blobs', ['checksum_sha256'], unique=False)
+    op.create_index(op.f('ix_file_blobs_tenant_id'), 'file_blobs', ['tenant_id'], unique=False)
+    op.create_table('access_group_role_assignments',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('group_id', sa.String(length=36), nullable=False),
+    sa.Column('role_id', sa.String(length=36), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['group_id'], ['access_groups.id'], name=op.f('fk_access_group_role_assignments_group_id_access_groups'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['role_id'], ['access_roles.id'], name=op.f('fk_access_group_role_assignments_role_id_access_roles'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_group_role_assignments')),
+    sa.UniqueConstraint('tenant_id', 'group_id', 'role_id', name='uq_group_role_assignments')
+    )
+    op.create_index(op.f('ix_access_group_role_assignments_group_id'), 'access_group_role_assignments', ['group_id'], unique=False)
+    op.create_index(op.f('ix_access_group_role_assignments_role_id'), 'access_group_role_assignments', ['role_id'], unique=False)
+    op.create_index(op.f('ix_access_group_role_assignments_tenant_id'), 'access_group_role_assignments', ['tenant_id'], unique=False)
+    op.create_table('access_system_role_assignments',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('account_id', sa.String(length=36), nullable=False),
+    sa.Column('role_id', sa.String(length=36), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['account_id'], ['access_accounts.id'], name=op.f('fk_access_system_role_assignments_account_id_access_accounts'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['role_id'], ['access_roles.id'], name=op.f('fk_access_system_role_assignments_role_id_access_roles'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_system_role_assignments')),
+    sa.UniqueConstraint('account_id', 'role_id', name='uq_system_role_assignments')
+    )
+    op.create_index(op.f('ix_access_system_role_assignments_account_id'), 'access_system_role_assignments', ['account_id'], unique=False)
+    op.create_index(op.f('ix_access_system_role_assignments_role_id'), 'access_system_role_assignments', ['role_id'], unique=False)
+    op.create_table('access_users',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('account_id', sa.String(length=36), nullable=False),
+    sa.Column('email', sa.String(length=320), nullable=False),
+    sa.Column('display_name', sa.String(length=255), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('is_tenant_admin', sa.Boolean(), nullable=False),
+    sa.Column('auth_provider', sa.String(length=50), nullable=False),
+    sa.Column('password_hash', sa.String(length=500), nullable=True),
+    sa.Column('last_login_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('mail_profile_policy', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['account_id'], ['access_accounts.id'], name=op.f('fk_access_users_account_id_access_accounts'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_users')),
+    sa.UniqueConstraint('tenant_id', 'account_id', name='uq_users_tenant_account'),
+    sa.UniqueConstraint('tenant_id', 'email', name='uq_users_tenant_email')
+    )
+    op.create_index(op.f('ix_access_users_account_id'), 'access_users', ['account_id'], unique=False)
+    op.create_index(op.f('ix_access_users_email'), 'access_users', ['email'], unique=False)
+    op.create_index(op.f('ix_access_users_tenant_id'), 'access_users', ['tenant_id'], unique=False)
+    op.create_table('admin_governance_template_assignments',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('template_id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('mode', sa.String(length=20), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['template_id'], ['admin_governance_templates.id'], name=op.f('fk_admin_governance_template_assignments_template_id_admin_governance_templates'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_admin_governance_template_assignments')),
+    sa.UniqueConstraint('template_id', 'tenant_id', name='uq_governance_template_tenant')
+    )
+    op.create_index(op.f('ix_admin_governance_template_assignments_template_id'), 'admin_governance_template_assignments', ['template_id'], unique=False)
+    op.create_index(op.f('ix_admin_governance_template_assignments_tenant_id'), 'admin_governance_template_assignments', ['tenant_id'], unique=False)
+    op.create_table('access_api_keys',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('user_id', sa.String(length=36), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('prefix', sa.String(length=16), nullable=False),
+    sa.Column('key_hash', sa.String(length=128), nullable=False),
+    sa.Column('scopes', sa.JSON(), nullable=False),
+    sa.Column('expires_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('last_used_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_access_api_keys_user_id_access_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_api_keys'))
+    )
+    op.create_index(op.f('ix_access_api_keys_prefix'), 'access_api_keys', ['prefix'], unique=False)
+    op.create_index(op.f('ix_access_api_keys_tenant_id'), 'access_api_keys', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_access_api_keys_user_id'), 'access_api_keys', ['user_id'], unique=False)
+    op.create_table('access_auth_sessions',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('user_id', sa.String(length=36), nullable=False),
+    sa.Column('account_id', sa.String(length=36), nullable=False),
+    sa.Column('token_hash', sa.String(length=128), nullable=False),
+    sa.Column('csrf_token_hash', sa.String(length=128), nullable=True),
+    sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('last_seen_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('user_agent', sa.String(length=500), nullable=True),
+    sa.Column('ip_address', sa.String(length=100), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['account_id'], ['access_accounts.id'], name=op.f('fk_access_auth_sessions_account_id_access_accounts'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_access_auth_sessions_user_id_access_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_auth_sessions'))
+    )
+    op.create_index(op.f('ix_access_auth_sessions_account_id'), 'access_auth_sessions', ['account_id'], unique=False)
+    op.create_index(op.f('ix_access_auth_sessions_expires_at'), 'access_auth_sessions', ['expires_at'], unique=False)
+    op.create_index(op.f('ix_access_auth_sessions_revoked_at'), 'access_auth_sessions', ['revoked_at'], unique=False)
+    op.create_index(op.f('ix_access_auth_sessions_tenant_id'), 'access_auth_sessions', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_access_auth_sessions_token_hash'), 'access_auth_sessions', ['token_hash'], unique=True)
+    op.create_index(op.f('ix_access_auth_sessions_user_id'), 'access_auth_sessions', ['user_id'], unique=False)
+    op.create_table('access_user_group_memberships',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('user_id', sa.String(length=36), nullable=False),
+    sa.Column('group_id', sa.String(length=36), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['group_id'], ['access_groups.id'], name=op.f('fk_access_user_group_memberships_group_id_access_groups'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_access_user_group_memberships_user_id_access_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_user_group_memberships')),
+    sa.UniqueConstraint('tenant_id', 'user_id', 'group_id', name='uq_user_group_memberships')
+    )
+    op.create_index(op.f('ix_access_user_group_memberships_group_id'), 'access_user_group_memberships', ['group_id'], unique=False)
+    op.create_index(op.f('ix_access_user_group_memberships_tenant_id'), 'access_user_group_memberships', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_access_user_group_memberships_user_id'), 'access_user_group_memberships', ['user_id'], unique=False)
+    op.create_table('access_user_role_assignments',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('user_id', sa.String(length=36), nullable=False),
+    sa.Column('role_id', sa.String(length=36), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['role_id'], ['access_roles.id'], name=op.f('fk_access_user_role_assignments_role_id_access_roles'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_access_user_role_assignments_user_id_access_users'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_access_user_role_assignments')),
+    sa.UniqueConstraint('tenant_id', 'user_id', 'role_id', name='uq_user_role_assignments')
+    )
+    op.create_index(op.f('ix_access_user_role_assignments_role_id'), 'access_user_role_assignments', ['role_id'], unique=False)
+    op.create_index(op.f('ix_access_user_role_assignments_tenant_id'), 'access_user_role_assignments', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_access_user_role_assignments_user_id'), 'access_user_role_assignments', ['user_id'], unique=False)
+    op.create_table('campaigns',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('owner_user_id', sa.String(length=36), nullable=True),
+    sa.Column('owner_group_id', sa.String(length=36), nullable=True),
+    sa.Column('external_id', sa.String(length=255), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('status', sa.String(length=50), nullable=False),
+    sa.Column('current_version_id', sa.String(length=36), nullable=True),
+    sa.Column('settings', sa.JSON(), nullable=False),
+    sa.Column('mail_profile_policy', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_campaigns_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_group_id'], ['access_groups.id'], name=op.f('fk_campaigns_owner_group_id_access_groups'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['access_users.id'], name=op.f('fk_campaigns_owner_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaigns')),
+    sa.UniqueConstraint('tenant_id', 'external_id', name='uq_campaigns_tenant_external_id')
+    )
+    op.create_index(op.f('ix_campaigns_created_by_user_id'), 'campaigns', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_campaigns_external_id'), 'campaigns', ['external_id'], unique=False)
+    op.create_index(op.f('ix_campaigns_owner_group_id'), 'campaigns', ['owner_group_id'], unique=False)
+    op.create_index(op.f('ix_campaigns_owner_user_id'), 'campaigns', ['owner_user_id'], unique=False)
+    op.create_index(op.f('ix_campaigns_status'), 'campaigns', ['status'], unique=False)
+    op.create_index(op.f('ix_campaigns_tenant_id'), 'campaigns', ['tenant_id'], unique=False)
+    op.create_table('file_assets',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('owner_type', sa.String(length=20), nullable=False),
+    sa.Column('owner_user_id', sa.String(length=36), nullable=True),
+    sa.Column('owner_group_id', sa.String(length=36), nullable=True),
+    sa.Column('current_version_id', sa.String(length=36), nullable=True),
+    sa.Column('display_path', sa.String(length=1000), nullable=False),
+    sa.Column('filename', sa.String(length=500), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('deleted_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('metadata', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_file_assets_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_group_id'], ['access_groups.id'], name=op.f('fk_file_assets_owner_group_id_access_groups'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['access_users.id'], name=op.f('fk_file_assets_owner_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_assets'))
+    )
+    op.create_index(op.f('ix_file_assets_created_by_user_id'), 'file_assets', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_file_assets_current_version_id'), 'file_assets', ['current_version_id'], unique=False)
+    op.create_index(op.f('ix_file_assets_deleted_at'), 'file_assets', ['deleted_at'], unique=False)
+    op.create_index(op.f('ix_file_assets_display_path'), 'file_assets', ['display_path'], unique=False)
+    op.create_index(op.f('ix_file_assets_filename'), 'file_assets', ['filename'], unique=False)
+    op.create_index(op.f('ix_file_assets_owner_group_id'), 'file_assets', ['owner_group_id'], unique=False)
+    op.create_index(op.f('ix_file_assets_owner_type'), 'file_assets', ['owner_type'], unique=False)
+    op.create_index(op.f('ix_file_assets_owner_user_id'), 'file_assets', ['owner_user_id'], unique=False)
+    op.create_index(op.f('ix_file_assets_tenant_id'), 'file_assets', ['tenant_id'], unique=False)
+    op.create_table('file_folders',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('owner_type', sa.String(length=20), nullable=False),
+    sa.Column('owner_user_id', sa.String(length=36), nullable=True),
+    sa.Column('owner_group_id', sa.String(length=36), nullable=True),
+    sa.Column('path', sa.String(length=1000), nullable=False),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('deleted_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('metadata', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_file_folders_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_group_id'], ['access_groups.id'], name=op.f('fk_file_folders_owner_group_id_access_groups'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['access_users.id'], name=op.f('fk_file_folders_owner_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_folders'))
+    )
+    op.create_index(op.f('ix_file_folders_created_by_user_id'), 'file_folders', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_file_folders_deleted_at'), 'file_folders', ['deleted_at'], unique=False)
+    op.create_index(op.f('ix_file_folders_owner_group_id'), 'file_folders', ['owner_group_id'], unique=False)
+    op.create_index(op.f('ix_file_folders_owner_type'), 'file_folders', ['owner_type'], unique=False)
+    op.create_index(op.f('ix_file_folders_owner_user_id'), 'file_folders', ['owner_user_id'], unique=False)
+    op.create_index(op.f('ix_file_folders_path'), 'file_folders', ['path'], unique=False)
+    op.create_index(op.f('ix_file_folders_tenant_id'), 'file_folders', ['tenant_id'], unique=False)
+    op.create_index('uq_file_folders_active_group_path', 'file_folders', ['tenant_id', 'owner_group_id', 'path'], unique=True, sqlite_where=sa.text("owner_type = 'group' AND deleted_at IS NULL"), postgresql_where=sa.text("owner_type = 'group' AND deleted_at IS NULL"))
+    op.create_index('uq_file_folders_active_user_path', 'file_folders', ['tenant_id', 'owner_user_id', 'path'], unique=True, sqlite_where=sa.text("owner_type = 'user' AND deleted_at IS NULL"), postgresql_where=sa.text("owner_type = 'user' AND deleted_at IS NULL"))
+    op.create_table('mail_server_profiles',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=True),
+    sa.Column('scope_type', sa.String(length=20), nullable=False),
+    sa.Column('scope_id', sa.String(length=36), nullable=True),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('slug', sa.String(length=100), nullable=False),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('smtp_config', sa.JSON(), nullable=False),
+    sa.Column('smtp_username', sa.String(length=320), nullable=True),
+    sa.Column('smtp_password_encrypted', sa.Text(), nullable=True),
+    sa.Column('imap_config', sa.JSON(), nullable=True),
+    sa.Column('imap_username', sa.String(length=320), nullable=True),
+    sa.Column('imap_password_encrypted', sa.Text(), nullable=True),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('updated_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_mail_server_profiles_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['updated_by_user_id'], ['access_users.id'], name=op.f('fk_mail_server_profiles_updated_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_mail_server_profiles')),
+    sa.UniqueConstraint('tenant_id', 'slug', name='uq_mail_server_profiles_tenant_slug')
+    )
+    op.create_index(op.f('ix_mail_server_profiles_created_by_user_id'), 'mail_server_profiles', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_mail_server_profiles_is_active'), 'mail_server_profiles', ['is_active'], unique=False)
+    op.create_index('ix_mail_server_profiles_scope', 'mail_server_profiles', ['scope_type', 'scope_id'], unique=False)
+    op.create_index(op.f('ix_mail_server_profiles_scope_id'), 'mail_server_profiles', ['scope_id'], unique=False)
+    op.create_index(op.f('ix_mail_server_profiles_scope_type'), 'mail_server_profiles', ['scope_type'], unique=False)
+    op.create_index(op.f('ix_mail_server_profiles_tenant_id'), 'mail_server_profiles', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_mail_server_profiles_updated_by_user_id'), 'mail_server_profiles', ['updated_by_user_id'], unique=False)
+    op.create_table('attachment_instances',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('owner_user_id', sa.String(length=36), nullable=True),
+    sa.Column('campaign_id', sa.String(length=36), nullable=True),
+    sa.Column('blob_id', sa.String(length=36), nullable=False),
+    sa.Column('logical_name', sa.String(length=500), nullable=True),
+    sa.Column('filename', sa.String(length=500), nullable=False),
+    sa.Column('tags', sa.JSON(), nullable=False),
+    sa.Column('metadata', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['blob_id'], ['attachment_blobs.id'], name=op.f('fk_attachment_instances_blob_id_attachment_blobs'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_attachment_instances_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['access_users.id'], name=op.f('fk_attachment_instances_owner_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_attachment_instances'))
+    )
+    op.create_index(op.f('ix_attachment_instances_blob_id'), 'attachment_instances', ['blob_id'], unique=False)
+    op.create_index(op.f('ix_attachment_instances_campaign_id'), 'attachment_instances', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_attachment_instances_owner_user_id'), 'attachment_instances', ['owner_user_id'], unique=False)
+    op.create_index(op.f('ix_attachment_instances_tenant_id'), 'attachment_instances', ['tenant_id'], unique=False)
+    op.create_table('audit_log',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('scope', sa.String(length=20), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=True),
+    sa.Column('user_id', sa.String(length=36), nullable=True),
+    sa.Column('api_key_id', sa.String(length=36), nullable=True),
+    sa.Column('action', sa.String(length=100), nullable=False),
+    sa.Column('object_type', sa.String(length=100), nullable=True),
+    sa.Column('object_id', sa.String(length=100), nullable=True),
+    sa.Column('details', sa.JSON(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['api_key_id'], ['access_api_keys.id'], name=op.f('fk_audit_log_api_key_id_access_api_keys'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['user_id'], ['access_users.id'], name=op.f('fk_audit_log_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_audit_log'))
+    )
+    op.create_index(op.f('ix_audit_log_action'), 'audit_log', ['action'], unique=False)
+    op.create_index(op.f('ix_audit_log_api_key_id'), 'audit_log', ['api_key_id'], unique=False)
+    op.create_index(op.f('ix_audit_log_object_id'), 'audit_log', ['object_id'], unique=False)
+    op.create_index(op.f('ix_audit_log_object_type'), 'audit_log', ['object_type'], unique=False)
+    op.create_index(op.f('ix_audit_log_scope'), 'audit_log', ['scope'], unique=False)
+    op.create_index('ix_audit_log_scope_created_at', 'audit_log', ['scope', 'created_at'], unique=False)
+    op.create_index(op.f('ix_audit_log_tenant_id'), 'audit_log', ['tenant_id'], unique=False)
+    op.create_index('ix_audit_log_tenant_scope_created_at', 'audit_log', ['tenant_id', 'scope', 'created_at'], unique=False)
+    op.create_index(op.f('ix_audit_log_user_id'), 'audit_log', ['user_id'], unique=False)
+    op.create_table('campaign_shares',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_id', sa.String(length=36), nullable=False),
+    sa.Column('target_type', sa.String(length=20), nullable=False),
+    sa.Column('target_id', sa.String(length=36), nullable=False),
+    sa.Column('permission', sa.String(length=20), nullable=False),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_shares_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_campaign_shares_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_shares')),
+    sa.UniqueConstraint('campaign_id', 'target_type', 'target_id', name='uq_campaign_share_target')
+    )
+    op.create_index(op.f('ix_campaign_shares_campaign_id'), 'campaign_shares', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_campaign_shares_created_by_user_id'), 'campaign_shares', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_campaign_shares_revoked_at'), 'campaign_shares', ['revoked_at'], unique=False)
+    op.create_index(op.f('ix_campaign_shares_target_id'), 'campaign_shares', ['target_id'], unique=False)
+    op.create_index(op.f('ix_campaign_shares_target_type'), 'campaign_shares', ['target_type'], unique=False)
+    op.create_index(op.f('ix_campaign_shares_tenant_id'), 'campaign_shares', ['tenant_id'], unique=False)
+    op.create_table('campaign_versions',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_id', sa.String(length=36), nullable=False),
+    sa.Column('version_number', sa.Integer(), nullable=False),
+    sa.Column('raw_json', sa.JSON(), nullable=False),
+    sa.Column('schema_version', sa.String(length=50), nullable=False),
+    sa.Column('source_filename', sa.String(length=500), nullable=True),
+    sa.Column('source_base_path', sa.String(length=1000), nullable=True),
+    sa.Column('workflow_state', sa.String(length=50), nullable=False),
+    sa.Column('current_flow', sa.String(length=50), nullable=False),
+    sa.Column('current_step', sa.String(length=100), nullable=True),
+    sa.Column('is_complete', sa.Boolean(), nullable=False),
+    sa.Column('editor_state', sa.JSON(), nullable=False),
+    sa.Column('autosaved_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('published_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('locked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('locked_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('user_lock_state', sa.String(length=20), nullable=True),
+    sa.Column('user_locked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('user_locked_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('validation_summary', sa.JSON(), nullable=True),
+    sa.Column('build_summary', sa.JSON(), nullable=True),
+    sa.Column('execution_snapshot', sa.JSON(), nullable=True),
+    sa.Column('execution_snapshot_hash', sa.String(length=64), nullable=True),
+    sa.Column('execution_snapshot_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_versions_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['locked_by_user_id'], ['access_users.id'], name=op.f('fk_campaign_versions_locked_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['user_locked_by_user_id'], ['access_users.id'], name=op.f('fk_campaign_versions_user_locked_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_versions')),
+    sa.UniqueConstraint('campaign_id', 'version_number', name='uq_campaign_versions_campaign_number')
+    )
+    op.create_index(op.f('ix_campaign_versions_campaign_id'), 'campaign_versions', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_current_flow'), 'campaign_versions', ['current_flow'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_execution_snapshot_hash'), 'campaign_versions', ['execution_snapshot_hash'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_locked_by_user_id'), 'campaign_versions', ['locked_by_user_id'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_user_lock_state'), 'campaign_versions', ['user_lock_state'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_user_locked_by_user_id'), 'campaign_versions', ['user_locked_by_user_id'], unique=False)
+    op.create_index(op.f('ix_campaign_versions_workflow_state'), 'campaign_versions', ['workflow_state'], unique=False)
+    op.create_table('file_shares',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('file_asset_id', sa.String(length=36), nullable=False),
+    sa.Column('target_type', sa.String(length=20), nullable=False),
+    sa.Column('target_id', sa.String(length=36), nullable=False),
+    sa.Column('permission', sa.String(length=20), nullable=False),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_file_shares_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['file_asset_id'], ['file_assets.id'], name=op.f('fk_file_shares_file_asset_id_file_assets'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_shares')),
+    sa.UniqueConstraint('file_asset_id', 'target_type', 'target_id', 'revoked_at', name='uq_file_shares_active_target')
+    )
+    op.create_index(op.f('ix_file_shares_created_by_user_id'), 'file_shares', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_file_shares_file_asset_id'), 'file_shares', ['file_asset_id'], unique=False)
+    op.create_index(op.f('ix_file_shares_revoked_at'), 'file_shares', ['revoked_at'], unique=False)
+    op.create_index(op.f('ix_file_shares_target_id'), 'file_shares', ['target_id'], unique=False)
+    op.create_index(op.f('ix_file_shares_target_type'), 'file_shares', ['target_type'], unique=False)
+    op.create_index(op.f('ix_file_shares_tenant_id'), 'file_shares', ['tenant_id'], unique=False)
+    op.create_table('file_versions',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('file_asset_id', sa.String(length=36), nullable=False),
+    sa.Column('blob_id', sa.String(length=36), nullable=False),
+    sa.Column('version_number', sa.Integer(), nullable=False),
+    sa.Column('filename_at_upload', sa.String(length=500), nullable=False),
+    sa.Column('display_path_at_upload', sa.String(length=1000), nullable=False),
+    sa.Column('content_type', sa.String(length=255), nullable=True),
+    sa.Column('size_bytes', sa.Integer(), nullable=False),
+    sa.Column('checksum_sha256', sa.String(length=64), nullable=False),
+    sa.Column('created_by_user_id', sa.String(length=36), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['blob_id'], ['file_blobs.id'], name=op.f('fk_file_versions_blob_id_file_blobs'), ondelete='RESTRICT'),
+    sa.ForeignKeyConstraint(['created_by_user_id'], ['access_users.id'], name=op.f('fk_file_versions_created_by_user_id_access_users'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['file_asset_id'], ['file_assets.id'], name=op.f('fk_file_versions_file_asset_id_file_assets'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_file_versions')),
+    sa.UniqueConstraint('file_asset_id', 'version_number', name='uq_file_versions_asset_number')
+    )
+    op.create_index(op.f('ix_file_versions_blob_id'), 'file_versions', ['blob_id'], unique=False)
+    op.create_index(op.f('ix_file_versions_checksum_sha256'), 'file_versions', ['checksum_sha256'], unique=False)
+    op.create_index(op.f('ix_file_versions_created_by_user_id'), 'file_versions', ['created_by_user_id'], unique=False)
+    op.create_index(op.f('ix_file_versions_file_asset_id'), 'file_versions', ['file_asset_id'], unique=False)
+    op.create_index(op.f('ix_file_versions_tenant_id'), 'file_versions', ['tenant_id'], unique=False)
+    op.create_table('campaign_jobs',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_version_id', sa.String(length=36), nullable=False),
+    sa.Column('entry_index', sa.Integer(), nullable=False),
+    sa.Column('entry_id', sa.String(length=255), nullable=True),
+    sa.Column('recipient_email', sa.String(length=320), nullable=True),
+    sa.Column('subject', sa.String(length=998), nullable=True),
+    sa.Column('message_id_header', sa.String(length=255), nullable=True),
+    sa.Column('eml_storage_key', sa.String(length=1000), nullable=True),
+    sa.Column('eml_local_path', sa.String(length=1000), nullable=True),
+    sa.Column('eml_size_bytes', sa.Integer(), nullable=True),
+    sa.Column('eml_sha256', sa.String(length=64), nullable=True),
+    sa.Column('build_status', sa.String(length=50), nullable=False),
+    sa.Column('validation_status', sa.String(length=50), nullable=False),
+    sa.Column('queue_status', sa.String(length=50), nullable=False),
+    sa.Column('send_status', sa.String(length=50), nullable=False),
+    sa.Column('imap_status', sa.String(length=50), nullable=False),
+    sa.Column('attempt_count', sa.Integer(), nullable=False),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('queued_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('claimed_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('claim_token', sa.String(length=36), nullable=True),
+    sa.Column('smtp_started_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('outcome_unknown_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('sent_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('resolved_recipients', sa.JSON(), nullable=True),
+    sa.Column('resolved_attachments', sa.JSON(), nullable=False),
+    sa.Column('issues_snapshot', sa.JSON(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_jobs_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['campaign_version_id'], ['campaign_versions.id'], name=op.f('fk_campaign_jobs_campaign_version_id_campaign_versions'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_jobs')),
+    sa.UniqueConstraint('campaign_version_id', 'entry_index', name='uq_campaign_jobs_version_entry')
+    )
+    op.create_index(op.f('ix_campaign_jobs_build_status'), 'campaign_jobs', ['build_status'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_campaign_id'), 'campaign_jobs', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_campaign_version_id'), 'campaign_jobs', ['campaign_version_id'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_claim_token'), 'campaign_jobs', ['claim_token'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_eml_sha256'), 'campaign_jobs', ['eml_sha256'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_entry_id'), 'campaign_jobs', ['entry_id'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_imap_status'), 'campaign_jobs', ['imap_status'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_queue_status'), 'campaign_jobs', ['queue_status'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_recipient_email'), 'campaign_jobs', ['recipient_email'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_send_status'), 'campaign_jobs', ['send_status'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_tenant_id'), 'campaign_jobs', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_campaign_jobs_validation_status'), 'campaign_jobs', ['validation_status'], unique=False)
+    op.create_table('campaign_attachment_uses',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_version_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_job_id', sa.String(length=36), nullable=True),
+    sa.Column('entry_index', sa.Integer(), nullable=True),
+    sa.Column('entry_id', sa.String(length=255), nullable=True),
+    sa.Column('file_asset_id', sa.String(length=36), nullable=False),
+    sa.Column('file_version_id', sa.String(length=36), nullable=False),
+    sa.Column('file_blob_id', sa.String(length=36), nullable=False),
+    sa.Column('filename_used', sa.String(length=500), nullable=False),
+    sa.Column('checksum_sha256', sa.String(length=64), nullable=False),
+    sa.Column('size_bytes', sa.Integer(), nullable=False),
+    sa.Column('content_type', sa.String(length=255), nullable=True),
+    sa.Column('use_stage', sa.String(length=20), nullable=False),
+    sa.Column('used_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_attachment_uses_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['campaign_job_id'], ['campaign_jobs.id'], name=op.f('fk_campaign_attachment_uses_campaign_job_id_campaign_jobs'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['campaign_version_id'], ['campaign_versions.id'], name=op.f('fk_campaign_attachment_uses_campaign_version_id_campaign_versions'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['file_asset_id'], ['file_assets.id'], name=op.f('fk_campaign_attachment_uses_file_asset_id_file_assets'), ondelete='RESTRICT'),
+    sa.ForeignKeyConstraint(['file_blob_id'], ['file_blobs.id'], name=op.f('fk_campaign_attachment_uses_file_blob_id_file_blobs'), ondelete='RESTRICT'),
+    sa.ForeignKeyConstraint(['file_version_id'], ['file_versions.id'], name=op.f('fk_campaign_attachment_uses_file_version_id_file_versions'), ondelete='RESTRICT'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_attachment_uses')),
+    sa.UniqueConstraint('campaign_job_id', 'file_version_id', 'filename_used', 'use_stage', name='uq_campaign_attachment_uses_job_file_stage')
+    )
+    op.create_index(op.f('ix_campaign_attachment_uses_campaign_id'), 'campaign_attachment_uses', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_campaign_job_id'), 'campaign_attachment_uses', ['campaign_job_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_campaign_version_id'), 'campaign_attachment_uses', ['campaign_version_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_entry_id'), 'campaign_attachment_uses', ['entry_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_file_asset_id'), 'campaign_attachment_uses', ['file_asset_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_file_blob_id'), 'campaign_attachment_uses', ['file_blob_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_file_version_id'), 'campaign_attachment_uses', ['file_version_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_tenant_id'), 'campaign_attachment_uses', ['tenant_id'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_use_stage'), 'campaign_attachment_uses', ['use_stage'], unique=False)
+    op.create_index(op.f('ix_campaign_attachment_uses_used_at'), 'campaign_attachment_uses', ['used_at'], unique=False)
+    op.create_table('campaign_issues',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('tenant_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_id', sa.String(length=36), nullable=False),
+    sa.Column('campaign_version_id', sa.String(length=36), nullable=True),
+    sa.Column('job_id', sa.String(length=36), nullable=True),
+    sa.Column('severity', sa.String(length=20), nullable=False),
+    sa.Column('code', sa.String(length=100), nullable=False),
+    sa.Column('message', sa.Text(), nullable=False),
+    sa.Column('source', sa.String(length=255), nullable=True),
+    sa.Column('behavior', sa.String(length=50), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['campaign_id'], ['campaigns.id'], name=op.f('fk_campaign_issues_campaign_id_campaigns'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['campaign_version_id'], ['campaign_versions.id'], name=op.f('fk_campaign_issues_campaign_version_id_campaign_versions'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['job_id'], ['campaign_jobs.id'], name=op.f('fk_campaign_issues_job_id_campaign_jobs'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_campaign_issues'))
+    )
+    op.create_index(op.f('ix_campaign_issues_campaign_id'), 'campaign_issues', ['campaign_id'], unique=False)
+    op.create_index(op.f('ix_campaign_issues_campaign_version_id'), 'campaign_issues', ['campaign_version_id'], unique=False)
+    op.create_index(op.f('ix_campaign_issues_code'), 'campaign_issues', ['code'], unique=False)
+    op.create_index(op.f('ix_campaign_issues_job_id'), 'campaign_issues', ['job_id'], unique=False)
+    op.create_index(op.f('ix_campaign_issues_severity'), 'campaign_issues', ['severity'], unique=False)
+    op.create_index(op.f('ix_campaign_issues_tenant_id'), 'campaign_issues', ['tenant_id'], unique=False)
+    op.create_table('imap_append_attempts',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('job_id', sa.String(length=36), nullable=False),
+    sa.Column('attempt_number', sa.Integer(), nullable=False),
+    sa.Column('folder', sa.String(length=500), nullable=True),
+    sa.Column('status', sa.String(length=50), nullable=False),
+    sa.Column('error_message', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['job_id'], ['campaign_jobs.id'], name=op.f('fk_imap_append_attempts_job_id_campaign_jobs'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_imap_append_attempts'))
+    )
+    op.create_index(op.f('ix_imap_append_attempts_job_id'), 'imap_append_attempts', ['job_id'], unique=False)
+    op.create_table('send_attempts',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('job_id', sa.String(length=36), nullable=False),
+    sa.Column('attempt_number', sa.Integer(), nullable=False),
+    sa.Column('status', sa.String(length=50), nullable=False),
+    sa.Column('claim_token', sa.String(length=36), nullable=True),
+    sa.Column('smtp_status_code', sa.Integer(), nullable=True),
+    sa.Column('smtp_response', sa.Text(), nullable=True),
+    sa.Column('error_type', sa.String(length=255), nullable=True),
+    sa.Column('error_message', sa.Text(), nullable=True),
+    sa.Column('started_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+    sa.ForeignKeyConstraint(['job_id'], ['campaign_jobs.id'], name=op.f('fk_send_attempts_job_id_campaign_jobs'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_send_attempts'))
+    )
+    op.create_index(op.f('ix_send_attempts_claim_token'), 'send_attempts', ['claim_token'], unique=False)
+    op.create_index(op.f('ix_send_attempts_job_id'), 'send_attempts', ['job_id'], unique=False)
+    op.create_index(op.f('ix_send_attempts_status'), 'send_attempts', ['status'], unique=False)
+    _seed_core_defaults()
+
+
+def downgrade() -> None:
+    op.drop_table('send_attempts')
+    op.drop_table('imap_append_attempts')
+    op.drop_table('campaign_issues')
+    op.drop_table('campaign_attachment_uses')
+    op.drop_table('campaign_jobs')
+    op.drop_table('file_versions')
+    op.drop_table('file_shares')
+    op.drop_table('campaign_versions')
+    op.drop_table('campaign_shares')
+    op.drop_table('audit_log')
+    op.drop_table('attachment_instances')
+    op.drop_table('mail_server_profiles')
+    op.drop_table('file_folders')
+    op.drop_table('file_assets')
+    op.drop_table('campaigns')
+    op.drop_table('access_user_role_assignments')
+    op.drop_table('access_user_group_memberships')
+    op.drop_table('access_auth_sessions')
+    op.drop_table('access_api_keys')
+    op.drop_table('admin_governance_template_assignments')
+    op.drop_table('access_users')
+    op.drop_table('access_system_role_assignments')
+    op.drop_table('access_group_role_assignments')
+    op.drop_table('file_blobs')
+    op.drop_table('core_system_settings')
+    op.drop_table('core_change_sequence_retention_floor')
+    op.drop_table('core_change_sequence')
+    op.drop_table('audit_outbox_events')
+    op.drop_table('attachment_blobs')
+    op.drop_table('admin_governance_templates')
+    op.drop_table('access_roles')
+    op.drop_table('access_groups')
+    op.drop_table('access_accounts')
+    op.drop_table('core_scopes')

docs/ACCESS_RBAC_MODEL.md

@@ -0,0 +1,343 @@
+# GovOPlaN RBAC And Resource-Access Model
+
+**Updated:** 2026-07-11
+
+## Authorization Equation
+
+An operation is permitted only when every applicable layer allows it:
+
+```text
+effective role/API-key capability
+AND resource ownership/share access
+AND workflow state
+AND active governance/policy constraints
+```
+
+RBAC answers what an actor may do. ACLs answer which resource the actor may do
+it to. Workflow state and policy decide whether the operation is currently
+valid.
+
+## Identity And Scope
+
+```text
+Account                         global login identity
++- User membership               tenant-local identity
+   +- direct tenant roles
+   +- active group memberships
+   |  +- inherited tenant roles
+   +- tenant-local API keys
+
+Account
++- direct system-role assignments
+```
+
+A browser session has one active tenant membership. System privileges do not
+silently grant tenant data access. API keys remain tenant-local and receive the
+intersection of their configured scopes and their owner's live tenant scopes on
+every request.
+
+## Wildcards
+
+```text
+tenant:*   every canonical tenant permission
+system:*   every canonical system permission
+*          legacy alias interpreted as tenant:* only
+```
+
+Tenant wildcards never grant system permissions.
+
+## Canonical Tenant Permissions
+
+Campaigns:
+
+```text
+campaign:read
+campaign:create
+campaign:update
+campaign:copy
+campaign:archive
+campaign:delete
+campaign:share
+campaign:validate
+campaign:build
+campaign:review
+campaign:send_test
+campaign:queue
+campaign:control
+campaign:send
+campaign:retry
+campaign:reconcile
+```
+
+Recipients:
+
+```text
+recipients:read
+recipients:write
+recipients:import
+recipients:export
+```
+
+Files:
+
+```text
+files:read
+files:download
+files:upload
+files:organize
+files:share
+files:delete
+files:admin
+```
+
+Reports and audit:
+
+```text
+reports:read
+reports:export
+reports:send
+audit:read
+```
+
+Mail servers:
+
+```text
+mail_servers:read
+mail_servers:use
+mail_servers:test
+mail_servers:write
+mail_servers:manage_credentials
+```
+
+Tenant administration:
+
+```text
+admin:users:read
+admin:users:create
+admin:users:update
+admin:users:suspend
+
+admin:groups:read
+admin:groups:write
+admin:groups:manage_members
+
+admin:roles:read
+admin:roles:write
+admin:roles:assign
+
+admin:api_keys:read
+admin:api_keys:create
+admin:api_keys:revoke
+
+admin:settings:read
+admin:settings:write
+admin:policies:read
+admin:policies:write
+```
+
+## Canonical System Permissions
+
+```text
+system:tenants:read
+system:tenants:create
+system:tenants:update
+system:tenants:suspend
+
+system:accounts:read
+system:accounts:create
+system:accounts:update
+system:accounts:suspend
+
+system:roles:read
+system:roles:write
+system:roles:assign
+
+system:access:read
+system:access:assign
+
+system:audit:read
+system:settings:read
+system:settings:write
+system:governance:read
+system:governance:write
+```
+
+`system:access:*` remains a read/assignment boundary for cross-tenant and
+system access handling. It is not a separate primary UI area.
+
+## Default Tenant Roles
+
+- **Owner:** `tenant:*`. At least one active operational owner must remain.
+- **Tenant administrator:** settings, policies, users, groups, roles, API keys,
+  and read access to campaigns/files/reports/audit. Real delivery remains
+  separately delegable.
+- **Administrator:** all tenant permissions for upgraded installations.
+- **Access administrator:** membership and assignment management within
+  delegation limits.
+- **Campaign manager:** prepare, validate, and build campaigns; no review
+  approval or real delivery by default.
+- **Reviewer:** inspect and approve prepared campaign messages.
+- **Sender:** mock-test, queue, control, send, retry, and reconcile prepared
+  campaigns; can use/test approved mail profiles.
+- **File manager:** managed file operations without campaign delivery rights.
+- **Viewer:** read campaigns, recipients, files, and reports.
+- **Auditor:** read campaigns, recipient evidence, reports, and audit records;
+  export detailed evidence.
+
+## Default System Roles
+
+- **System owner:** `system:*`, protected. At least one active account must
+  retain it.
+- **System administrator:** all specific system permissions, editable and not
+  protected.
+- **System auditor:** read-only system registry/settings/governance/audit role,
+  editable.
+
+## Delegation Ceiling
+
+For role definition, assignment, and API-key creation:
+
+```text
+requested scopes subset of actor delegateable scopes
+```
+
+Rules:
+
+1. Tenant roles may contain tenant scopes only.
+2. System roles may contain system scopes only.
+3. Definition rights and assignment rights are separate.
+4. Group definition and group membership management are separate.
+5. API-key scopes are intersected with the owner's current effective scopes on
+   every request.
+6. Suspended accounts, users, tenants, or groups stop contributing access
+   immediately.
+7. Administrative updates are field-sensitive; a user with only status
+   authority cannot change role assignments.
+
+## Campaign Ownership And ACLs
+
+A campaign has exactly one owner:
+
+```text
+owner user OR owner group
+```
+
+Additional active shares may target users or groups with `read` or `write`.
+
+Resolution:
+
+- owner user: read and write;
+- member of owner group: read and write;
+- explicit read share: read;
+- explicit write share: read and write;
+- `tenant:*`: tenant-wide ACL bypass;
+- ordinary campaign permission without ownership/share: no object access.
+
+ACLs do not add capabilities. A write share still needs the specific permission
+for update, validation, review, send, report, retry, or reconciliation.
+
+## Files
+
+The current file access model distinguishes tenant-level file capabilities from
+space/folder/file ownership:
+
+| Scope | Meaning |
+| --- | --- |
+| `files:read` | browse/read visible file spaces and metadata |
+| `files:download` | download file content when ACL permits |
+| `files:upload` | create files in writable spaces |
+| `files:organize` | create folders, move files, and update metadata where ACL permits |
+| `files:share` | share files/spaces according to owner and policy rules |
+| `files:delete` | delete or retire files where ACL permits |
+| `files:admin` | tenant-wide administration of user/group file spaces |
+
+External file connections and spaces are additionally constrained by connector
+policy and owner/group assignment in the files module.
+
+## Resource Access Explanations
+
+The access module exposes a diagnostic endpoint for explaining why a principal
+can see or operate on a concrete resource:
+
+```text
+GET /api/v1/admin/access/resource-explanation
+```
+
+Required query values:
+
+| Field | Meaning |
+| --- | --- |
+| `user_id` | Tenant membership to explain. The current module UIs pass the signed-in user. |
+| `resource_type` | Module-owned type such as `file`, `folder`, or `campaign`. |
+| `resource_id` | Stable module resource identifier. |
+| `action` | Permission/action being explained, for example `files:file:read`. |
+| `tenant_id` | Optional tenant override for system/admin contexts. |
+
+The access module always contributes effective-scope provenance for the action.
+Installed modules may add resource provenance by exposing a
+`ResourceAccessExplanationProvider` through a capability consumed by access.
+Providers should return only facts they own, using these provenance kinds:
+
+| Kind | Meaning |
+| --- | --- |
+| `resource` | The concrete resource or an explicit not-found result. |
+| `owner` | Matching user/group ownership. |
+| `share` | Matching explicit user/group/tenant share. |
+| `policy` | Administrative bypass or policy-derived grant. |
+| `role` / `right` | Scope and role provenance from access itself. |
+
+Files currently registers `files.access` and explains file assets plus folders.
+Persisted folders use their database ID. Folder rows inferred from file paths use
+a deterministic virtual ID:
+
+```text
+virtual-folder:v1:<tenant_id>:<owner_type>:<owner_id>:<base64url(normalized_path)>
+```
+
+The files provider validates virtual folder IDs before returning provenance: the
+tenant and owner must match the resource ID, and at least one active file must
+exist below the normalized folder path. This keeps virtual folder explanations
+stable without forcing every inferred tree node to become a stored folder row.
+
+Campaign currently registers `campaigns.access` and explains the campaign
+ownership/sharing object itself. Finer-grained campaign sub-objects are tracked
+separately in `govoplan-campaign#50` until their resource identifiers and access
+rules are decided.
+
+Cross-user resource explanation is a policy feature, not a module-local UI
+detail. Until `govoplan-policy#6` is resolved, module UIs should default to
+current-user explanation and avoid importing access-admin user-picking
+components.
+
+## Mail Servers
+
+| Scope | Meaning |
+| --- | --- |
+| `mail_servers:read` | profile metadata and effective policy visibility |
+| `mail_servers:use` | use an allowed profile for a campaign or message flow |
+| `mail_servers:test` | run connectivity tests without revealing secrets |
+| `mail_servers:write` | create/update profile metadata where policy allows |
+| `mail_servers:manage_credentials` | create/replace SMTP/IMAP secrets or lower-level credentials where policy allows |
+
+Reusable encrypted profiles exist. Effective usability is also constrained by
+hierarchical mail-profile policy, ownership, allowed/forced profile sets,
+credential inheritance mode, lower-level override switches, and allow/deny
+patterns.
+
+## Compatibility Aliases
+
+Compatibility aliases may exist in backend code for upgraded installations, but
+new UI and docs should use canonical scopes.
+
+Current alias direction:
+
+```text
+*                      -> tenant:*
+system:tenants:write   -> create/update/suspend tenant scopes
+system:access:write    -> system access assignment/write scopes
+```
+
+A separate `retention:*` family is not currently canonical because retention is
+managed through system settings and tenant policy scopes. Add it only if
+retention operation duties need separation from general policy/settings
+administration.

docs/ACTION_EFFECT_AUTOMATION_LAYER.md

@@ -0,0 +1,121 @@
+# Action, Effect, And Automation Layer
+
+GovOPlaN needs an automation layer because administrative processes will not be
+only linear screen flows. Workflows, schedules, imports, connectors, policies,
+and external events all need to request governed actions without bypassing the
+same safety rules that apply to human users.
+
+The first implementation should live in `govoplan-workflow` and core contracts.
+Create a separate `govoplan-automation` module only if action planning,
+schedulers, rule execution, or cross-module automation become too broad for
+workflow ownership.
+
+## Layer Purpose
+
+The automation layer should provide:
+
+- a typed action catalogue
+- a typed effect catalogue
+- consequence preview before execution
+- policy and permission checks
+- idempotent execution
+- audit and provenance records
+- retry, quarantine, and manual exception handling
+- system-actor execution without hiding responsibility
+
+Automation is not a shortcut around module boundaries. It is a governed caller
+of module capabilities.
+
+## Action Definition
+
+An `ActionDefinition` describes something a human or system actor can request.
+
+Recommended fields:
+
+- `action_key`
+- owning module
+- input schema
+- actor requirements and required scopes
+- required capabilities
+- policy checks
+- risk level
+- reversibility class: reversible, compensatable, corrective-only, or
+  irreversible
+- expected effects
+- idempotency key strategy
+- audit event names
+- preview provider
+
+Examples:
+
+- create a case from a form submission
+- assign a task
+- generate a document from a template
+- send a postbox message
+- send an email notification
+- append evidence to records
+- create a payment request
+- call an external connector
+
+## Effect Definition
+
+An `EffectDefinition` describes the expected and observed result of an action.
+
+Recommended fields:
+
+- `effect_key`
+- affected module and resource references
+- external system references where applicable
+- created, changed, deleted, sent, notified, locked, or retained markers
+- visibility and privacy classification
+- audit event references
+- rollback or compensation hints
+- operator-facing explanation
+
+Effects should be recorded even when execution fails partially. This makes
+manual recovery and audit review possible.
+
+## Execution Model
+
+The runner should execute an action plan as follows:
+
+1. Resolve actor context: human, delegated actor, or system actor.
+2. Validate input schema.
+3. Resolve required module capabilities.
+4. Run permission and policy checks.
+5. Generate a consequence preview.
+6. Reserve or verify the idempotency key.
+7. Execute the owning module capability.
+8. Record observed effects.
+9. Emit events and audit records.
+10. Mark the command complete, retryable, quarantined, or requiring manual
+    intervention.
+
+The runner must never advance workflow state past a required side effect unless
+the action definition explicitly allows asynchronous completion and the pending
+state is visible.
+
+## Failure States
+
+Automation should use explicit failure states:
+
+- `blocked`: policy, permission, missing capability, or invalid input prevents
+  execution.
+- `retryable`: transient transport, timeout, rate-limit, or lock conflict.
+- `quarantined`: unexpected response, schema mismatch, unsafe partial result,
+  or unknown external state.
+- `manual_required`: human decision or correction is needed.
+- `compensation_required`: a later action must correct an already observed
+  side effect.
+
+These states should be visible in workflow, task, and admin diagnostics.
+
+## Boundary
+
+Core may own stable DTOs, registry contracts, and generic audit/event hooks.
+`govoplan-workflow` should own the first runner because workflow is the first
+module that coordinates cross-module process actions.
+
+Domain modules own their own action providers. For example, templates own
+document generation actions, postbox owns postbox message actions, and
+connectors own external handoff actions.

docs/CODEX_WORKFLOW.md

@@ -0,0 +1,85 @@
+# Codex Workflow
+
+This project is split across the core runner and sibling module repositories. Codex works best when all active repositories are writable from the start and routine checks use targeted commands.
+
+## Personal Codex Config
+
+Put machine-specific access in `~/.codex/config.toml`, not in a tracked project file:
+
+```toml
+model = "gpt-5.5"
+model_reasoning_effort = "xhigh"
+personality = "pragmatic"
+
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+approvals_reviewer = "user"
+
+[sandbox_workspace_write]
+writable_roots = [
+  "/mnt/DATA/git",
+]
+network_access = false
+
+[projects."/mnt/DATA/git/govoplan-core"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-access"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-organizations"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-identity"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-mail"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-files"]
+trust_level = "trusted"
+
+[projects."/mnt/DATA/git/govoplan-campaign"]
+trust_level = "trusted"
+```
+
+The broad writable root reduces approval churn. The explicit project trust entries allow project-local `AGENTS.md` guidance to load for each repository.
+
+## Repository Guidance
+
+Each active repository has an `AGENTS.md` file. These files define ownership, module boundaries, and focused commands for Codex. Keep durable project conventions there instead of repeating them in every prompt.
+
+Use `~/.codex/config.toml` for personal defaults, auth/runtime settings, writable roots, and trust decisions. Avoid checking in absolute-path writable roots or model preferences unless they are intentionally team-wide.
+
+Use Gitea issues as the canonical backlog and state log. See `docs/GITEA_ISSUES.md` for label setup, TODO import, and Codex issue update commands. Durable docs should describe stable behavior; changing work state belongs on the issue.
+
+## Focused Verification
+
+Use the consolidated script after changes that touch module discovery, optional integrations, shared mail components, mailbox listing, or cross-module WebUI behavior:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/checks/check-focused.sh
+```
+
+For smaller changes, prefer the narrow command named in the relevant `AGENTS.md` file. Examples:
+
+```bash
+cd /mnt/DATA/git/govoplan-core
+/mnt/DATA/git/govoplan/.venv/bin/python -m unittest tests.test_module_system
+
+cd /mnt/DATA/git/govoplan-mail
+/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
+
+cd /mnt/DATA/git/govoplan-core/webui
+PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run test:module-permutations
+```
+
+## Usage Discipline
+
+- Prefer `rg`, `sed`, and targeted test commands.
+- Avoid broad recursive scans and full builds unless the change warrants them.
+- Keep generated build/test folders ignored.
+- Keep optional module behavior behind core registry/capability/module metadata boundaries.
+- Create or update Gitea issues for TODOs, follow-ups, blockers, and feature requests instead of keeping local backlog files.
+- Do not start persistent dev servers unless the user asks.

docs/CONFIGURATION_PACKAGES.md

@@ -0,0 +1,335 @@
+# GovOPlaN Configuration Packages
+
+Configuration packages are reusable, versioned preconfigurations for a working
+GovOPlaN capability. They sit above modules: a module installs code,
+migrations, routes, permissions, and capabilities; a configuration package wires
+installed modules into a concrete operational setup.
+
+Example: an application-handling package could configure a public portal form,
+a case workflow, task creation, a mail template, payment processing, access
+roles, audit evidence, and the interface bindings between those modules.
+
+The guiding reference scenario is the government-operations permit journey in
+`docs/GOVOPLAN_MASTER_ROADMAP.md`: a person applies through the portal,
+uploads files, receives workflow-driven messages and appointment proposals, has
+a case opened, gets a permit generated from a template, and completes payment.
+Configuration packages are the mechanism that should make such processes
+reusable and safely importable.
+
+This document is durable architecture context and should be mirrored to the
+Gitea wiki. Active implementation should be tracked in Gitea issues.
+
+## Goals
+
+- Import a preconfiguration from a trusted catalog or uploaded package.
+- Detect which modules, module versions, and capabilities are required.
+- Detect which configuration fragments must be created, updated, or bound.
+- Explain import problems and offer actionable resolution paths.
+- Ask the operator only for data needed to make the package work.
+- Export an existing working configuration as a reusable package.
+- Support signed catalogs so approved configurations can be shared, adapted,
+  re-exported, and provided to other installations.
+
+## Vocabulary
+
+| Term | Meaning |
+| --- | --- |
+| Module | Installable product code with manifest, migrations, routes, permissions, WebUI, events, and capabilities. |
+| Configuration | Module-owned settings and resources that make behavior concrete: workflows, forms, templates, roles, policies, connector profiles, routing rules, and defaults. |
+| Interface | A typed contract between modules: capabilities, commands, events, DTOs, data bindings, and UI extension points. |
+| Data | Operator- or tenant-provided values needed for a working setup: legal text, sender addresses, account mappings, payment provider credentials, templates, defaults, and optionally reference data. |
+
+The system should communicate these four layers explicitly:
+
+```text
+module = what can exist
+configuration = what should exist here
+interface = how configured parts connect
+data = what the operator must provide for this deployment
+```
+
+## Package Model
+
+A configuration package should be a signed, portable manifest plus module-owned
+configuration fragments. The package is not a database dump. It should be
+declarative, idempotent, tenant-aware, and explicit about secrets and external
+systems.
+
+Required package metadata:
+
+- stable package id, name, version, description, publisher, and license
+- supported GovOPlaN core/module compatibility bounds
+- required modules with version constraints
+- optional modules with conditional behavior
+- required capabilities, commands, event subscriptions, and UI extension points
+- configuration fragments grouped by owning module
+- interface bindings between fragments
+- data requirements to collect from the operator
+- preflight checks and post-import health checks
+- migration or transformation rules for older package versions
+- provenance, export source metadata, and signature metadata
+
+Configuration fragments are interpreted only by the module that owns them. For
+example, workflow imports workflow definitions; forms imports form schemas;
+mail imports mail templates and delivery defaults; payments imports payment
+profiles; access imports groups, roles, and permission assignments.
+
+## Module Provider Contract
+
+Each module that wants to participate should expose a configuration-package
+provider capability. The core orchestrator should not understand module internals
+or write module-owned tables directly.
+
+Baseline provider responsibilities:
+
+- publish JSON Schema or equivalent typed schemas for importable/exportable
+  fragments
+- publish data requirements that can be rendered by a generic wizard
+- validate fragments without applying them
+- report missing dependencies, missing permissions, conflicts, and unsafe
+  changes
+- produce a dry-run plan with create, update, bind, skip, and blocked actions
+- apply fragments idempotently inside module-owned boundaries
+- export selected module-owned configuration into portable fragments
+- redact secrets and mark secret placeholders during export
+- provide post-apply health checks and operator-facing diagnostics
+
+Provider operations should be versioned. The first stable contract can be small:
+
+```text
+describe() -> schemas, supported fragment types, exported scopes
+preflight(package_fragment, context) -> diagnostics, required_data, plan
+apply(package_fragment, supplied_data, context) -> result, created_refs
+export(selection, context) -> fragment, data_placeholders, warnings
+health(import_result, context) -> diagnostics
+```
+
+The initial core contract lives in
+`govoplan_core.core.configuration_packages`. Modules register providers through
+module-specific capability keys and implement the `ConfigurationProvider`
+protocol. The generic `configuration.provider` key names the contract and can be
+used in package requirements; concrete providers such as `access.configuration`
+are resolved by the admin package wizard. The first DTO surface includes package
+manifests, module/capability requirements, module-owned fragments, diagnostics,
+required operator data, dry-run plan items, apply results, export selections,
+and export results.
+
+The initial implementation includes provider-neutral orchestration helpers:
+
+- `dry_run_configuration_package(...)`
+- `apply_configuration_package(...)`
+- `export_configuration_package(...)`
+
+The first concrete provider is `govoplan_access.backend.configuration_provider`.
+It supports access-owned `roles`, `groups`, and `group_role_assignments`
+fragments and applies them idempotently.
+
+The admin wizard backend starts with these routes:
+
+- `GET /api/v1/admin/configuration-packages/catalog`
+- `POST /api/v1/admin/configuration-packages/dry-run`
+- `POST /api/v1/admin/configuration-packages/apply`
+- `POST /api/v1/admin/configuration-packages/export`
+
+## Import Flow
+
+1. Select a package from a trusted catalog or upload a package file.
+2. Verify signature, channel, publisher trust, package compatibility, and schema.
+3. Resolve required modules against installed modules and the module package
+   catalog.
+4. Produce a dependency plan for modules that must be installed or upgraded.
+5. Ask the operator for required data using a focused wizard.
+6. Run dry-run preflight across all participating module providers.
+7. Show problems grouped by severity, owner module, and resolution.
+8. Apply module/package changes in a dependency-safe order.
+9. Run post-import health checks and show the final working status.
+10. Store import provenance, package version, supplied non-secret metadata, and
+    audit events.
+
+The wizard should display everything necessary and nothing unnecessary. Generic
+sections should cover package trust, dependency plan, required data, conflicts,
+review, and result. Module-specific fields should appear only when the selected
+package and installed modules require them.
+
+## Problem Model
+
+Import diagnostics should be structured and actionable, not free-text logs.
+Every problem should include severity, owner, affected object, explanation, and
+at least one suggested resolution when the system can infer it.
+
+Common diagnostic types:
+
+- missing module or incompatible module version
+- missing capability or disabled optional integration
+- missing operator-supplied data
+- missing permission or insufficient administrator scope
+- unresolved interface binding between modules
+- conflicting existing configuration
+- external service not reachable or credential test failed
+- policy or tenant-governance violation
+- unsafe overwrite, downgrade, or destructive change
+- schema validation failure
+- post-import health-check failure
+
+Resolution actions can include install module, upgrade module, enable
+integration, provide value, choose existing object, rename imported object,
+skip optional fragment, replace existing configuration, or cancel import.
+
+## Export Flow
+
+Export should be possible from a working tenant or system configuration, but it
+must be intentional about data boundaries.
+
+1. Select export scope: system, tenant, module set, workflow, form, case type,
+   portal flow, or another domain object.
+2. Ask participating modules to export owned fragments and data placeholders.
+3. Classify exported material as configuration, reference data, sample data,
+   secrets, or deployment-local data.
+4. Redact secrets by default and replace them with data requirements.
+5. Let the operator choose whether to include reference/sample data.
+6. Validate the assembled package by running the same preflight path against a
+   clean target context where possible.
+7. Sign the package or produce an unsigned development package.
+8. Optionally publish the package metadata to a configuration catalog.
+
+Exported packages should record provenance: source GovOPlaN version, module
+versions, exporter identity, timestamp, selected scope, redactions, and
+validation status.
+
+## Catalogs And Trust
+
+Configuration catalogs should follow the existing module package catalog model:
+a file-backed or remotely fetched JSON catalog with Ed25519 signatures, channel
+gating, trusted key ids, and operator-controlled trust policy.
+
+The initial catalog validator mirrors the module catalog environment model with
+configuration-specific names:
+
+```bash
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG=/srv/govoplan/configuration-catalogs/stable.json
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_URL=https://govoplan.example/configuration-catalogs/stable.json
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_CACHE=/srv/govoplan/runtime/configuration-catalog-cache/stable.json
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_REQUIRE_SIGNATURE=true
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_APPROVED_CHANNELS=stable,lts
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_TRUSTED_KEYS_FILE=/srv/govoplan/trust/configuration-catalog-keyring.json
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_SEQUENCE_STATE=/srv/govoplan/runtime/configuration-catalog-sequences.json
+GOVOPLAN_CONFIGURATION_PACKAGE_CATALOG_ENFORCE_SEQUENCE=true
+```
+
+Catalog entries should include:
+
+- package id, version, name, description, publisher, tags, and channel
+- package artifact URL or repository ref
+- signature metadata for the package artifact
+- required modules and version ranges for quick compatibility display
+- package category such as workflow, portal, case type, governance, connector,
+  report, or tenant baseline
+- maturity flags such as official, verified, example, local, deprecated
+
+The catalog verifies that a package is approved to view and import. The package
+itself must still be signed and validated before use.
+
+## Example Package
+
+Application handling through a public portal:
+
+Required modules:
+
+- `portal` for the public user-facing entry point
+- `forms` for the application form and validation
+- `cases` for the case record and case type
+- `workflow` for status transitions and automation
+- `tasks` for internal task creation
+- `templates` for mail/template rendering
+- `mail` for delivery profile and outbound message sending
+- `payments` for provider configuration and payment capture
+- `access` for roles, groups, and permissions
+- `audit` for import, case, mail, and payment evidence
+
+Required configuration:
+
+- portal route and access policy
+- form schema, validation rules, confirmation texts, and attachments
+- case type, fields, lifecycle states, and retention classification
+- workflow steps, transitions, assignees, and completion triggers
+- task template and queue/group assignment
+- mail template and delivery rule
+- payment product, amount rules, provider profile, and webhook binding
+- access roles/groups for clerks, reviewers, supervisors, and operators
+- audit event categories and evidence retention defaults
+
+Required operator data:
+
+- tenant or organizational unit
+- service name and public contact details
+- portal URL/path and legal imprint/privacy text
+- mail sender profile and reply-to mailbox
+- payment provider credentials or test-mode selection
+- responsible groups or users for task assignment
+- escalation contacts and deadlines
+- template wording and localized text overrides
+
+Potential problems:
+
+- `payments` is missing or the provider capability is unavailable
+- mail transport test fails for the selected sender profile
+- imported role names conflict with existing tenant roles
+- workflow references a task queue that does not exist
+- public portal base URL is not configured
+- required privacy/legal text is empty
+- webhook endpoint cannot be validated from the payment provider
+
+## Ownership
+
+Core should own:
+
+- package and catalog signature validation
+- dependency resolution against installed modules and module catalogs
+- orchestration of provider preflight/apply/export operations
+- generic import/export APIs and audit envelope
+- generic wizard shell and problem display components
+
+Modules should own:
+
+- schemas and semantics for their own fragments
+- module-specific validation, apply, export, and health checks
+- module-specific UI capabilities only when generic generated controls are not
+  sufficient
+- redaction and classification of module-owned secrets or sensitive data
+
+Access should own configuration fragments for users, groups, roles,
+permissions, API keys, and principal mappings. It should not own workflow, mail,
+payment, form, or portal semantics.
+
+Admin should expose the operator-facing catalog, import, export, and history
+screens through admin route contributions. The UI should keep the conceptual
+layers visible: modules, configuration, interfaces, and data.
+
+## Implementation Slices
+
+1. Define package manifest and diagnostic schemas.
+2. Add core configuration-package provider capability contracts.
+3. Implement catalog validation and package signature verification.
+4. Add dry-run orchestration against mock providers.
+5. Add admin catalog/import wizard screens using provider data requirements.
+6. Implement export/import providers for access-owned roles/groups first.
+7. Add providers in workflow/forms/templates/mail/payments/portal/cases/tasks as
+   those modules mature.
+8. Add round-trip tests: export a known setup, import into a clean tenant,
+   verify health checks.
+9. Add documentation and field-level help for package authors and operators.
+
+## Acceptance Criteria For Tracking Issue
+
+- A Gitea tracking issue exists in `govoplan-core` for the cross-cutting
+  feature.
+- The issue links module-specific follow-ups when implementation begins.
+- The first implementation exposes typed contracts rather than direct
+  cross-module imports.
+- A signed example catalog and unsigned development fixture exist.
+- A dry-run import can identify required modules, missing data, and conflicts
+  before applying changes.
+- An export can produce a package with secrets redacted into data requirements.
+- Admin UI shows a focused wizard and actionable diagnostic list.
+- Tests cover package validation, signature failure, dependency resolution,
+  provider preflight, export redaction, and import idempotency.

docs/DEPENDENCY_AUDITS.md

@@ -0,0 +1,70 @@
+# Dependency Audits
+
+GovOPlaN keeps dependency vulnerability checks reproducible but separate from
+the fast local smoke suite, because both Python and npm audits need network
+metadata and can fail for newly disclosed advisories without a source change.
+
+## Local Workflow
+
+Install the whole-product development dependencies once from the meta
+repository:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python -m pip install -r requirements-dev.txt
+```
+
+Run both backend and WebUI production audits:
+
+```bash
+cd /mnt/DATA/git/govoplan
+bash tools/checks/check-dependency-audits.sh
+```
+
+The script runs:
+
+- `tools/checks/check-dependency-hygiene.sh` for pip resolver consistency, stale
+  legacy editable package metadata, deprecated framework constants, and the
+  Starlette `TestClient` deprecation smoke when test dependencies are present
+- `python -m pip_audit --progress-spinner off`
+- `npm audit --omit=dev` in `webui`
+
+For fast local checks without vulnerability metadata lookups, run:
+
+```bash
+cd /mnt/DATA/git/govoplan
+CHECK_TESTCLIENT_DEPRECATIONS=1 \
+bash tools/checks/check-dependency-hygiene.sh
+```
+
+This is also part of `govoplan/tools/checks/check-focused.sh`, so resolver drift and
+deprecation regressions fail close to the code change that introduced them.
+
+Override tool paths when testing from a disposable environment:
+
+```bash
+PYTHON=/tmp/govoplan-audit/bin/python \
+NPM=/home/zemion/.nvm/versions/node/v22.22.3/bin/npm \
+GOVOPLAN_CORE_ROOT=/mnt/DATA/git/govoplan-core \
+bash /mnt/DATA/git/govoplan/tools/checks/check-dependency-audits.sh
+```
+
+## CI Workflow
+
+`govoplan/.gitea/workflows/dependency-audit.yml` installs release dependencies from
+tagged package refs, installs `pip-audit`, and runs the same script on pushes,
+pull requests, and a weekly schedule.
+
+The workflow intentionally uses release dependency refs instead of local
+`file:` or editable sibling paths. Development lockfiles may keep local module
+links, but release audit results should represent the installable product.
+
+## Recording Results
+
+When closing or triaging dependency-audit issues, add a short dated note under
+`docs/audits/`. Record:
+
+- the commands that were run
+- whether Python and npm passed
+- any advisories accepted as temporary risk
+- follow-up issue links for required upgrades

docs/DEPLOYMENT_OPERATOR_GUIDE.md

@@ -0,0 +1,426 @@
+# GovOPlaN Deployment Operator Guide
+
+This guide defines the current install/runtime configuration contract and the
+operator flow for a production-realistic self-hosted deployment. Keep secrets in
+the deployment environment or a secret manager; do not commit populated `.env`
+files.
+
+## Runtime Configuration Contract
+
+Self-hosted installability follows the staged approach documented in
+`SELF_HOSTED_INSTALLABILITY.md`: generate an explicit env template, validate it,
+run production-like rehearsal with Compose-backed dependencies, then use the
+installer CLI/daemon for package mutation under maintenance mode.
+
+Generate a deployment-local template:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python -m govoplan_core.commands.config env-template \
+  --profile self-hosted \
+  --generate-secrets \
+  --output .env.self-hosted
+```
+
+Validate the active shell environment before migration or startup:
+
+```bash
+set -a
+. .env.self-hosted
+set +a
+./.venv/bin/python -m govoplan_core.commands.config validate --profile self-hosted
+```
+
+### Required Runtime Identity
+
+| Setting | Required outside dev | Purpose |
+| --- | --- | --- |
+| `APP_ENV` | yes | Runtime profile. Use `prod`, `staging`, or a deployment-specific value outside local development. |
+| `MASTER_KEY_B64` | yes | Fernet key or base64 encoded 32-byte key used for encrypted module secrets. Rotate through an explicit operator plan. |
+| `DATABASE_URL` | yes | SQLAlchemy database URL for core and installed modules. SQLite is supported for dev/small installs; PostgreSQL is the preferred production target. |
+| `ENABLED_MODULES` | yes | Comma-separated startup module set. Keep `tenancy,access` enabled; keep `admin` enabled for operator UI. |
+
+Generate a local key for a new non-production environment:
+
+```bash
+python - <<'PY'
+from cryptography.fernet import Fernet
+print(Fernet.generate_key().decode())
+PY
+```
+
+### Database And Migrations
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `DATABASE_URL` | `postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev` | Local development and production-like profiles use PostgreSQL. Use `GOVOPLAN_DEV_DATABASE_BACKEND=sqlite` only for disposable SQLite runs. |
+| `GOVOPLAN_MIGRATION_TRACK` | `release` | Use the release track for normal runtime and deployments. Use `dev` only for fresh/disposable databases that intentionally replay detailed development migrations. |
+| `DEV_AUTO_MIGRATE_ENABLED` | `true` | Dev convenience only. Production should run migration commands explicitly during deployment. |
+| `DEV_BOOTSTRAP_ENABLED` | `false` | Dev bootstrap only. `govoplan_core.devserver` and `govoplan/tools/launch/launch-dev.sh` default it to `true`; use controlled first-admin creation outside dev. |
+
+Operator rule: take a database backup before applying migrations or destructive
+module retirement. For non-SQLite databases, configure deployment-specific
+backup/restore hooks for the module installer.
+
+### PostgreSQL Production Target
+
+PostgreSQL is the primary development and production target. SQLite remains
+supported only for tiny disposable profiles and unit-test style smoke runs.
+Production/staging deployments should use a managed PostgreSQL database and
+explicit migration commands.
+
+Install the full release profile from the meta repository so core, modules, and
+the `psycopg` driver are available:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python -m pip install -r requirements-release.txt
+```
+
+Example runtime database URLs:
+
+```bash
+export DATABASE_URL='postgresql+psycopg://govoplan:change-me@db.example.internal:5432/govoplan'
+export GOVOPLAN_DATABASE_URL_PGTOOLS='postgresql://govoplan:change-me@db.example.internal:5432/govoplan'
+```
+
+Use the SQLAlchemy URL for GovOPlaN. Use the pg-tools URL for `pg_dump`,
+`pg_restore`, and `psql`; these tools do not understand the
+`postgresql+psycopg://` driver marker.
+
+Bootstrap or upgrade the schema explicitly during deployment:
+
+```bash
+export APP_ENV=prod
+export ENABLED_MODULES=tenancy,access,admin,policy,audit,campaigns,files,mail,calendar,docs,ops
+./.venv/bin/python -m govoplan_core.commands.init_db \
+  --database-url "$DATABASE_URL"
+```
+
+Backup and restore-check before migration-bearing package changes:
+
+```bash
+pg_dump --format=custom \
+  --file "$PWD/runtime/govoplan-$(date +%Y%m%d%H%M%S).dump" \
+  "$GOVOPLAN_DATABASE_URL_PGTOOLS"
+pg_restore --list "$PWD/runtime/govoplan-YYYYMMDDHHMMSS.dump" >/dev/null
+```
+
+Restore a checked backup to the target database:
+
+```bash
+pg_restore --clean --if-exists \
+  --dbname "$GOVOPLAN_DATABASE_URL_PGTOOLS" \
+  "$PWD/runtime/govoplan-YYYYMMDDHHMMSS.dump"
+```
+
+For local development, create the host database described in
+`/mnt/DATA/git/govoplan/dev/postgres/README.md`, then run:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python -m govoplan_core.commands.init_db \
+  --database-url postgresql+psycopg://govoplan_dev@127.0.0.1:5432/govoplan_dev \
+  --with-dev-data
+./.venv/bin/python -m govoplan_core.devserver --smoke --no-reload
+tools/launch/launch-dev.sh
+```
+
+For disposable local validation against a throwaway PostgreSQL instance, use
+the bundled PostgreSQL testbed:
+
+```bash
+cd /mnt/DATA/git/govoplan/dev/postgres
+cp .env.example .env
+docker compose --env-file .env up -d
+
+cd /mnt/DATA/git/govoplan
+set -a
+. /mnt/DATA/git/govoplan/dev/postgres/.env
+set +a
+tools/checks/postgres-integration-check.py \
+  --database-url "$GOVOPLAN_POSTGRES_DATABASE_URL" \
+  --reset-schema
+```
+
+The integration check runs migrations and startup smoke checks across the
+standard module permutations. `--reset-schema` is destructive and belongs only
+on throwaway databases.
+
+### Broker And Workers
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `REDIS_URL` | `redis://redis:6379/0` | Celery broker/result backend when async workers are enabled. |
+| `CELERY_ENABLED` | `false` | Local/dev can send synchronously. Production campaign delivery should run workers and set this to `true`. |
+| `CELERY_QUEUES` | `send_email,append_sent,default` | Queue list expected by worker/process manager definitions. |
+
+Worker command:
+
+```bash
+python -m celery -A govoplan_core.celery_app:celery worker \
+  --queues send_email,append_sent,default \
+  --loglevel INFO
+```
+
+### Storage
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `FILE_STORAGE_BACKEND` | `local` | Use `local` for dev/small deployments; use object storage when files must scale independently. |
+| `FILE_STORAGE_LOCAL_ROOT` | `runtime/files` | Must live on durable storage and be backed up when `FILE_STORAGE_BACKEND=local`. |
+| `FILE_STORAGE_LOCAL_FALLBACK_ROOTS` | empty | Read-only fallback roots for migrated local files. |
+| `FILE_STORAGE_S3_ENDPOINT_URL` | empty | Object-store endpoint for the files module. |
+| `FILE_STORAGE_S3_REGION` | empty | Object-store region. |
+| `FILE_STORAGE_S3_ACCESS_KEY_ID` | empty | Secret; inject through deployment environment. |
+| `FILE_STORAGE_S3_SECRET_ACCESS_KEY` | empty | Secret; inject through deployment environment. |
+| `FILE_STORAGE_S3_BUCKET` | `files` | Managed-file object bucket. |
+
+Legacy `S3_*` settings remain for older storage paths but new deployments should
+prefer `FILE_STORAGE_*`.
+
+### HTTP, Cookies, And Base URLs
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `CORS_ORIGINS` | local dev origins | Set to the exact WebUI origins in staging/production. |
+| `AUTH_SESSION_COOKIE_NAME` | configured default | Change only through a controlled rollout because it logs users out. |
+| `AUTH_CSRF_COOKIE_NAME` | configured default | Must match WebUI/API deployment. |
+| `AUTH_COOKIE_SECURE` | `false` | Set `true` behind HTTPS. |
+| `AUTH_COOKIE_SAMESITE` | `lax` | Use a stricter value only after testing login and CSRF flows. |
+| `AUTH_COOKIE_DOMAIN` | empty | Set only when the API and WebUI intentionally share a parent domain. |
+
+Public URLs are currently supplied by deployment/reverse-proxy configuration and
+module settings. Do not hardcode them in core; configuration packages should ask
+for portal, WebUI, postbox, and notification URLs when they become relevant.
+
+### Module Catalogs, Licenses, And Trust Roots
+
+| Setting | Purpose |
+| --- | --- |
+| `GOVOPLAN_MODULE_PACKAGE_CATALOG_URL` or `GOVOPLAN_MODULE_PACKAGE_CATALOG` | Module package catalog source. |
+| `GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_FILE` | Preferred production keyring path. |
+| `GOVOPLAN_MODULE_PACKAGE_CATALOG_APPROVED_CHANNEL` | Approved catalog channel, for example `stable`. |
+| `GOVOPLAN_LICENSE_TRUSTED_KEYS_FILE` | Trusted license issuer keyring path. |
+| `GOVOPLAN_LICENSE_ENFORCEMENT` | Enables license enforcement when set to `true`. |
+
+Trust roots are deployment-managed and should not be editable through the
+running WebUI.
+
+### Mail Test Credentials
+
+Dedicated SMTP/IMAP test credentials belong to the mail/campaign test-bed
+configuration, not the core runtime contract. Store them in a local ignored
+`.env` file for the test bed or in CI secrets. Required values are:
+
+- SMTP host, port, TLS mode, username, password, and envelope/from address.
+- IMAP host, port, TLS mode, username, password, and append folder.
+- At least one recipient mailbox that is safe for automated send tests.
+
+## First Deployment Flow
+
+1. Create an environment file or secret set with the runtime contract above.
+2. Install the tagged core and module packages from meta `requirements-release.txt`.
+3. Build the WebUI from `webui/package.release.json` or deploy a prebuilt
+   artifact from the same release tag.
+4. Run database migrations with the target `DATABASE_URL`.
+5. Create the first tenant and system owner through the controlled bootstrap or
+   one-time admin command for the deployment.
+6. Start the API service with `govoplan_core.server.app:app`.
+7. Start workers when `CELERY_ENABLED=true`.
+8. Start the WebUI/reverse proxy and verify CORS/cookie settings.
+9. Open Admin > System > Modules, verify enabled modules, and save desired
+   module state if it differs from `ENABLED_MODULES`.
+10. Run health checks:
+
+```bash
+curl -fsS http://127.0.0.1:8000/health
+curl -fsS http://127.0.0.1:8000/api/v1/platform/modules
+```
+
+Authenticated health details require `system:settings:read`:
+
+```bash
+curl -fsS -H "X-API-Key: $GOVOPLAN_HEALTH_API_KEY" \
+  http://127.0.0.1:8000/health/details
+```
+
+## Production-Like Dev Profile
+
+Use this profile to verify deployment behavior without publishing packages or
+using real production credentials. The canonical launcher keeps API, worker, and
+WebUI code in the editable repositories while Docker provides PostgreSQL and
+Redis:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/launch/launch-production-like-dev.sh
+```
+
+The helper wrapper provides explicit lifecycle commands:
+
+```bash
+tools/launch/production-like-dev.sh validate-config
+tools/launch/production-like-dev.sh seed
+tools/launch/production-like-dev.sh start
+tools/launch/production-like-dev.sh stop
+tools/launch/production-like-dev.sh reset --yes
+```
+
+The launcher uses `govoplan/dev/production-like/.env` when present, otherwise
+the checked in `.env.example`. It runs:
+
+- PostgreSQL on `127.0.0.1:55433`
+- Redis on `127.0.0.1:56379`
+- explicit `ENABLED_MODULES`
+- explicit migrations and `--with-dev-data` bootstrap
+- API via the module-aware devserver
+- a Celery worker for `send_email,append_sent,default`
+- WebUI through the Vite dev server
+- durable local files under `runtime/production-like/files`
+
+This profile validates explicit migration execution, config loading, module
+discovery, route aggregation, local storage paths, Redis broker connectivity,
+worker heartbeats, and health/readiness startup without real production
+credentials. It does not replace a managed PostgreSQL/Redis/WebUI/worker
+deployment test.
+
+To stop PostgreSQL and Redis when the launcher exits:
+
+```bash
+GOVOPLAN_STOP_PROFILE_DEPENDENCIES_ON_EXIT=1 tools/launch/launch-production-like-dev.sh
+```
+
+## Module Install/Uninstall Operations
+
+Use Admin > System > Modules for planning. The running API server validates and
+queues install plans; it does not run pip/npm or restart itself from an HTTP
+request. Package mutation belongs to the trusted installer CLI/daemon in an
+operator shell while maintenance mode is active.
+
+Preflight from the server shell:
+
+```bash
+govoplan-module-installer --format shell
+```
+
+Apply a prepared plan directly from a controlled shell:
+
+```bash
+govoplan-module-installer --apply --build-webui
+```
+
+For production-like runs, prefer supervised mode with migrations, database
+backup/restore hooks, restart commands, and health checks:
+
+```bash
+govoplan-module-installer \
+  --supervise \
+  --migrate \
+  --restart-command 'systemctl restart govoplan-api' \
+  --restart-command 'systemctl restart govoplan-worker' \
+  --health-url http://127.0.0.1:8000/health \
+  --database-backup-command 'pg_dump --format=custom "$GOVOPLAN_DATABASE_URL_PGTOOLS" > "$GOVOPLAN_DATABASE_BACKUP_PATH"' \
+  --database-restore-check-command 'pg_restore --list "$GOVOPLAN_DATABASE_BACKUP_PATH" >/dev/null' \
+  --database-restore-command 'pg_restore --clean --if-exists --dbname "$GOVOPLAN_DATABASE_URL_PGTOOLS" "$GOVOPLAN_DATABASE_BACKUP_PATH"'
+```
+
+To let the admin UI submit work without executing package managers inside the
+API process, run the daemon in a separate operator shell:
+
+```bash
+govoplan-module-installer \
+  --daemon \
+  --migrate \
+  --build-webui \
+  --database-backup-command 'pg_dump --format=custom "$GOVOPLAN_DATABASE_URL_PGTOOLS" > "$GOVOPLAN_DATABASE_BACKUP_PATH"' \
+  --database-restore-check-command 'pg_restore --list "$GOVOPLAN_DATABASE_BACKUP_PATH" >/dev/null' \
+  --database-restore-command 'pg_restore --clean --if-exists --dbname "$GOVOPLAN_DATABASE_URL_PGTOOLS" "$GOVOPLAN_DATABASE_BACKUP_PATH"' \
+  --health-url http://127.0.0.1:8000/health \
+  --restart-command '<restart govoplan server>'
+```
+
+The daemon claims one queued request at a time and writes request/run records
+below `runtime/module-installer`. For process-manager one-shot usage or tests,
+use `--daemon-once`. Check daemon status with:
+
+```bash
+govoplan-module-installer --daemon-status --format json
+```
+
+The installer uses a runtime lock, snapshots `pip freeze` plus WebUI package
+files, writes a run record, and marks planned rows as applied only after all
+commands succeed. With `--migrate`, SQLite databases are backed up through
+SQLite's backup API; non-SQLite databases require
+`--database-backup-command`, `--database-restore-check-command`, and
+`--database-restore-command`.
+
+Database hook commands receive:
+
+- `GOVOPLAN_INSTALLER_RUN_DIR`
+- `GOVOPLAN_DATABASE_URL`
+- `GOVOPLAN_DATABASE_URL_PGTOOLS` for PostgreSQL tools
+- `GOVOPLAN_DATABASE_BACKUP_PATH`
+- `GOVOPLAN_DATABASE_BACKUP_METADATA`
+
+Avoid embedding secrets directly in commands; prefer environment variables,
+service credentials, or deployment-local secret injection.
+
+Inspect installer history and lock state from the operator shell:
+
+```bash
+govoplan-module-installer --list-runs --format json
+govoplan-module-installer --show-run <run-id> --format json
+govoplan-module-installer --lock-status --format json
+govoplan-module-installer --list-requests --format json
+govoplan-module-installer --show-request <request-id> --format json
+govoplan-module-installer --cancel-request <request-id> --format json
+govoplan-module-installer --retry-request <request-id> --format json
+```
+
+Rollback uses the saved run snapshot:
+
+```bash
+govoplan-module-installer --rollback <run-id>
+govoplan-module-installer --rollback <run-id> --database-restore-command '<override restore command>'
+```
+
+Uninstall is non-destructive by default. A planned uninstall row can set
+`destroy_data: true` to request destructive module retirement. The module must
+provide an automated retirement provider, and the installer snapshots the
+database before dropping module-owned tables.
+
+Run the rollback drill before relying on installer automation in a new
+environment:
+
+```bash
+/mnt/DATA/git/govoplan/tools/checks/module-installer-rollback-drill.py --format json
+```
+
+The drill uses temporary SQLite databases and simulated package commands. It
+does not install or uninstall real packages. It exercises:
+
+- package command failure followed by supervised rollback;
+- migration failure with a SQLite database snapshot;
+- restart-command failure;
+- health timeout after restart;
+- destructive retirement executor failure with database rollback;
+- PostgreSQL-style backup, restore-check, and restore hooks;
+- daemon heartbeat, request queue claim/update, retry/cancel, and stale lock
+  detection/removal.
+
+See `RELEASE_DEPENDENCIES.md` for release package refs, migration baseline
+checks, catalog trust, signing, keyring, replay, and license operation.
+
+## Operator Checklist
+
+- Runtime secrets are injected outside git.
+- `MASTER_KEY_B64` is set and backed up securely.
+- Database backup and restore commands are tested.
+- File/object storage is durable and backed up.
+- `CORS_ORIGINS` and cookie settings match the deployed WebUI origin.
+- Redis and workers are running before `CELERY_ENABLED=true`.
+- Module catalog and license keyrings are pinned locally.
+- Health endpoints are monitored.
+- Test SMTP/IMAP credentials are non-production and isolated.
+- Module installer rollback drill has passed in the deployment environment.

docs/DOCUMENTATION_MAP.md

@@ -0,0 +1,52 @@
+# GovOPlaN Documentation Map
+
+This map defines the source-of-truth documents for the current repository docs.
+Use it to avoid duplicating long procedures across architecture, release,
+operator, and roadmap pages.
+
+## Core Platform
+
+| Topic | Canonical document | Notes |
+| --- | --- | --- |
+| Module architecture and kernel contracts | `MODULE_ARCHITECTURE.md` | Stable module contracts, API efficiency contracts, durable boundary decisions, lifecycle, and WebUI contribution rules. |
+| RBAC and resource access | `ACCESS_RBAC_MODEL.md` | Current permission, role, API-key, and resource-access model. |
+| Governance hierarchy | `GOVERNANCE_MODEL.md` | System, tenant, user/group, campaign policy inheritance and admin UI structure. |
+| Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. |
+| Events and audit trace context | `EVENTS_AND_AUDIT.md` | Event dispatch semantics and audit payload conventions. |
+| Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. |
+| Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. |
+
+## Release And Operations
+
+| Topic | Canonical document | Notes |
+| --- | --- | --- |
+| Runtime configuration and operator flow | `DEPLOYMENT_OPERATOR_GUIDE.md` | Production/staging configuration, migrations, backups, installer operation, and rollback drill. |
+| Self-hosted installability | `SELF_HOSTED_INSTALLABILITY.md` | Packaging decision, generated env templates, config validation, production-like dev stack commands, and boundary gate. |
+| Release dependencies and catalogs | `RELEASE_DEPENDENCIES.md` | Release package refs, migration baselines, release lockfiles, catalog trust/licensing, catalog publishing, and release checklist. |
+| Dependency vulnerability audits | `DEPENDENCY_AUDITS.md` | Local and CI audit commands plus dated audit result notes. |
+| Remote WebUI bundle design | `REMOTE_WEBUI_BUNDLES.md` | Experimental controlled-deployment design; normal releases still use package builds. |
+
+## Product And Module Planning
+
+| Topic | Canonical document | Notes |
+| --- | --- | --- |
+| Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. |
+| UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. |
+| Interface ethics and design doctrine | `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` | Product-level doctrine for context, decision, consequence, contestability, responsibility, and traceability. |
+| Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. |
+| Configuration packages | `CONFIGURATION_PACKAGES.md` | Package model, provider contract, import/export flow, and tracking slices. |
+
+## Workflow Docs
+
+| Topic | Canonical document | Notes |
+| --- | --- | --- |
+| Gitea issues and wiki sync | `GITEA_ISSUES.md` | Issue labels, imports, wiki mirroring, and Codex state updates. |
+| Codex local workflow | `CODEX_WORKFLOW.md` | Local agent setup and focused verification commands. |
+
+## Cross-Repo Rule
+
+Core docs may keep strategy, kernel contracts, and routing decisions. Module
+repositories should own executable module behavior, concrete API/UI contracts,
+and operator notes for their own module. When content spans both, keep the
+durable decision in core and link to the module document for implementation
+details.

docs/EVENTS_AND_AUDIT.md

@@ -0,0 +1,203 @@
+# Events And Audit
+
+GovOPlaN uses a small kernel event contract first, not a broad command bus.
+Commands remain module-owned application-service methods or API endpoints until
+there is a concrete need for durable asynchronous command orchestration. Events
+are facts about completed work and are safe for audit, projections, optional
+module reactions, and operator diagnostics.
+
+## Production Transport Decision
+
+The first production target is a **database outbox plus in-process immediate
+dispatch**:
+
+- Use `govoplan_core.core.events.PlatformEvent` for domain and platform events.
+- Use `EventBus` as the in-process dispatch contract for same-process module
+  reactions that are safe to run inline.
+- Use the shared `audit_event` / `audit_from_principal` helper for audited
+  module actions. The helper persists the audit row and immediately publishes a
+  governed `PlatformEvent` whose `type` is the audit action.
+- Use `record_change` for module delta feeds. It persists the change-sequence
+  row and immediately publishes a generic module change event such as
+  `mail.profile.updated`.
+- Persist durable integration/workflow events through a database outbox before
+  acknowledging the state change that produced them.
+- Drain the outbox through a small dispatcher process. The dispatcher may call
+  in-process handlers in the same deployment first, but its storage contract is
+  database-backed.
+- Treat Redis/Celery as worker/job infrastructure, not as the authoritative
+  first event transport. A Celery dispatcher can consume the outbox later.
+- Keep the dispatch implementation pluggable behind the `PlatformEvent`
+  envelope so a future message broker can be added without changing event
+  producers.
+- Keep commands out of the kernel until workflows need retryable, durable,
+  operator-visible command records.
+
+This keeps the first contract small, PostgreSQL-friendly, auditable, and
+recoverable after process crashes. It also avoids making Redis a correctness
+dependency for deployments that only need synchronous mail/tests or light
+background work.
+
+## Dispatch Semantics
+
+Event producers should write their domain state and outbox event in the same
+database transaction wherever possible. Handlers must be idempotent because the
+outbox dispatcher can retry after a crash or timeout.
+
+Recommended first outbox columns:
+
+- `event_id`, `event_type`, `module_id`
+- `correlation_id`, `causation_id`
+- `payload`, `occurred_at`
+- `available_at`, `attempt_count`, `claimed_at`, `claim_token`
+- `processed_at`, `last_error`
+
+Inline `EventBus` handlers are allowed only for non-critical local reactions.
+Anything that must survive process failure, restart, package update, or worker
+redeployment belongs in the outbox.
+
+## Trace IDs
+
+Every `PlatformEvent` has:
+
+- `event_id`: unique ID for that event.
+- `correlation_id`: stable ID for the whole request, workflow, or job.
+- `causation_id`: the event ID or external operation ID that caused this
+  event.
+- `actor`: optional typed actor reference, for example user, API key, system
+  actor, delegated actor, or installer daemon.
+- `tenant`: optional tenant reference when the event is tenant-scoped.
+- `subject`: optional typed subject reference for the person, organization,
+  account, case, campaign, or other entity the event is about.
+- `resource`: optional typed resource reference for the object changed or
+  observed by the event.
+- `classification`: payload sensitivity, currently `public`, `internal`,
+  `confidential`, or `restricted`.
+- `payload`: JSON-serializable module-owned event details.
+
+The FastAPI app factory creates an event context for every request. It accepts
+`X-Correlation-ID` or `X-Request-ID` when the value is a compact safe trace ID,
+otherwise it generates a new ID. Responses include `X-Correlation-ID`.
+
+Audit logging reads the current event context and stores trace IDs in
+`details._trace`. Callers can also pass explicit `correlation_id` and
+`causation_id` to `audit_event` or `audit_from_principal`. The same trace is
+copied into the emitted `PlatformEvent`, so audit rows and event subscribers can
+be correlated without route-specific glue code.
+
+Admin and lifecycle code should use the compact operational detail shape
+documented in `govoplan-audit/docs/AUDIT_TRACE_CONTEXT.md`. The core
+`audit_operation_context` helper preserves `module_id`, `request_id`, `run_id`,
+`outcome`, and `_trace` while applying the shared audit redaction pass to
+additional detail values.
+
+## Audit MVP Boundary
+
+`govoplan-audit` owns:
+
+- the `audit_log` table and audit API routes
+- audit route contribution through its module manifest
+- audit retention behavior in cooperation with policy/retention settings
+- future audit sink/export capability implementations
+
+`govoplan-core` owns:
+
+- `AuditEvent` and `AuditSink` protocol contracts
+- request and event trace context
+- the compatibility `audit_event` helper while routes are still migrating
+- retention orchestration that calls module capabilities
+
+Feature modules should record audit facts through the shared helper or a future
+`audit.sink` capability. They should not import audit storage internals. Module
+state changes that only need delta-feed visibility should go through
+`record_change`; route-level business actions should still record a semantic
+audit action.
+
+## Initial Domain Event Inventory
+
+Access:
+
+- `access.account.created`
+- `access.account.updated`
+- `access.membership.created`
+- `access.membership.updated`
+- `access.group.created`
+- `access.group.updated`
+- `access.role.created`
+- `access.role.updated`
+- `access.role.deleted`
+- `access.api_key.created`
+- `access.api_key.revoked`
+- `access.session.created`
+- `access.session.revoked`
+
+Tenancy:
+
+- `tenant.created`
+- `tenant.updated`
+- `tenant.suspended`
+- `tenant.resumed`
+- `tenant.deletion_requested`
+- `tenant.erasure_completed`
+
+Policy:
+
+- `policy.system.updated`
+- `policy.tenant.updated`
+- `policy.user.updated`
+- `policy.group.updated`
+- `policy.campaign.updated`
+- `policy.effective_policy.changed`
+
+Files:
+
+- `files.file.uploaded`
+- `files.file.renamed`
+- `files.file.deleted`
+- `files.file.frozen`
+- `files.share.created`
+- `files.share.revoked`
+- `files.connector.imported`
+- `files.connector.access_denied`
+
+Mail:
+
+- `mail.profile.created`
+- `mail.profile.updated`
+- `mail.profile.credentials_rotated`
+- `mail.profile.tested`
+- `mail.message.sent`
+- `mail.message.send_failed`
+- `mail.imap.appended`
+- `mail.imap.append_failed`
+- `mail.mailbox.message_seen`
+
+Campaign:
+
+- `campaign.created`
+- `campaign.version.created`
+- `campaign.validated`
+- `campaign.built`
+- `campaign.reviewed`
+- `campaign.queued`
+- `campaign.send_started`
+- `campaign.recipient_attempted`
+- `campaign.recipient_delivered`
+- `campaign.recipient_failed`
+- `campaign.paused`
+- `campaign.resumed`
+- `campaign.cancelled`
+- `campaign.report.exported`
+
+## Event Payload Rules
+
+- Payloads must be JSON-serializable.
+- Use stable IDs, not ORM objects.
+- Include tenant ID when tenant-scoped.
+- Include actor/principal, subject, and resource references only as typed DTOs
+  or primitive IDs.
+- Set `classification` to the highest sensitivity needed by the envelope or
+  payload, not the lowest sensitivity of any individual field.
+- Do not include secrets, raw message bodies, full recipient lists, or file
+  content.
+- Put large evidence in owning module storage and reference it by ID.

docs/GITEA_ISSUES.md

@@ -0,0 +1,16 @@
+# Gitea Issues And Wiki Workflow
+
+The shared GovOPlaN Gitea issue, label, and wiki workflow tooling moved to the
+meta repository.
+
+Use:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/gitea/gitea-sync-labels.py --help
+tools/gitea/gitea-sync-wiki.py --help
+```
+
+Canonical documentation:
+
+- `/mnt/DATA/git/govoplan/docs/GITEA_ISSUES.md`

docs/GOVERNANCE_MODEL.md

@@ -0,0 +1,228 @@
+# GovOPlaN Governance Model
+
+**Updated:** 2026-07-09
+
+## Governance Rule
+
+System policy is authoritative for tenants and all lower levels. Each lower
+level may only narrow what it inherits:
+
+```text
+system
+-> tenant
+-> user or group owner
+-> campaign
+```
+
+Lower levels do not widen privileges, allowed profiles, retention durations, or
+credential rights granted by a higher level.
+
+## Administration Structure
+
+GovOPlaN separates system administration from scoped configuration:
+
+```text
+ADMINISTRATION
+- Modules
+- Packages
+- Maintenance
+- Changes
+
+GLOBAL
+- Tenants
+- Roles
+- Groups and users
+- File connectors
+- Mail servers
+- API keys
+- Retention
+
+TENANT
+- Roles
+- Groups and users
+- File connectors
+- Mail servers
+- API keys
+- Retention
+
+GROUP
+- File connectors
+- Mail servers
+- API keys
+- Retention
+
+USER
+- File connectors
+- Mail servers
+- API keys
+- Retention
+```
+
+System access scopes remain in the backend for assignment/read boundaries, but
+the UI should present the configuration hierarchy rather than a separate
+"system access" concept.
+
+## Tenant Governance
+
+System settings define tenant defaults and whether tenants may narrow selected
+options. Tenant overrides can only restrict:
+
+- custom groups;
+- custom roles;
+- tenant API keys.
+
+The backend enforces that tenant governance cannot widen system-denied
+privileges.
+
+## Mail-Profile Governance
+
+Mail server profiles may exist at these scopes:
+
+```text
+system
+tenant
+user
+group
+campaign
+```
+
+Effective campaign profile availability follows campaign ownership. A campaign
+owned by a user resolves through system, tenant, that user, and campaign
+policy. A group-owned campaign resolves through system, tenant, that group, and
+campaign policy.
+
+Policy semantics:
+
+- higher levels define the maximum available profile set;
+- lower levels can further restrict the set;
+- forced profiles mean the lower level must choose from the forced set;
+- a forced set with one profile effectively enforces that profile;
+- campaign-level profile creation is allowed only if the effective policy
+  permits it;
+- SMTP/IMAP credentials use one inheritance decision per protocol: lower levels
+  must inherit profile credentials, may inherit profile credentials, or must
+  provide local credentials;
+- the lower-level override switch for `smtp_credentials.inherit` and
+  `imap_credentials.inherit` controls whether descendants may change that
+  inheritance decision;
+- deny patterns always win over allow patterns;
+- empty or `*` allowlist means allow all except denied;
+- non-empty allowlist means at least one allow rule must match and no deny rule
+  may match.
+
+Pattern targets:
+
+```text
+SMTP hostname
+IMAP hostname
+envelope sender
+From header
+recipient domains
+```
+
+Ownership transfer is intentionally deferred as a two-step workflow: original
+owner initiates, new owner accepts and reselects/repairs the mail profile if
+their effective policy requires it.
+
+## File-Connector Governance
+
+File connector profiles and credentials are separated. Profiles describe
+external endpoints; credentials bind authentication material and policy to a
+scope. Concrete linked folders appear as file spaces in the files module.
+
+Governance follows the same inheritance shape as mail:
+
+- system and tenant policy can permit, require, or forbid lower-level
+  connections/credentials;
+- user or group ownership controls which spaces appear to principals;
+- spaces inherit endpoint and credential policy from their connector profile;
+- connector health and credential tests must not reveal plaintext secrets.
+
+## Retention Governance
+
+Retention policy is hierarchical:
+
+```text
+system -> tenant -> user/group -> campaign
+```
+
+Managed fields:
+
+- raw campaign JSON retention days;
+- generated EML retention days;
+- stored report detail retention days;
+- mock mailbox retention days;
+- audit detail retention days.
+
+Rules:
+
+- system may set concrete defaults or unlimited retention;
+- system exposes allow-limiting toggles per field;
+- tenants, users/groups, and campaigns may only shorten inherited retention
+  where the parent allows limiting;
+- blank lower-level values inherit;
+- mock mailbox retention is currently system-level because mock mailbox records
+  do not yet carry tenant/campaign ownership metadata;
+- dry-run/apply retention actions report affected classes before destructive
+  cleanup.
+
+## Role Definitions And Assignments
+
+### System Roles
+
+System roles define instance-wide permissions. `system:*` is stored as one
+wildcard and displayed as granting the full system catalogue. System owner is
+protected.
+
+### Tenant Roles
+
+Tenant roles can be system-governed templates or tenant-local definitions,
+subject to system tenant-governance settings and actor delegation ceilings.
+Wildcard counts are expanded against the canonical tenant catalogue.
+
+## Audit Access
+
+Audit access remains scope-separated:
+
+```text
+system audit -> system:audit:read
+tenant audit -> active tenant + audit:read
+```
+
+Audit pages use server pagination, filtering, and bounded grids.
+
+## Tenant Switching
+
+Tenant switching preserves the current URL when possible and falls back when a
+route/resource is not accessible in the new tenant context.
+
+The tenant selector is hidden for ordinary single-tenant accounts and visible
+for multi-tenant or system tenant-management contexts.
+
+## Administration DataGrid Contract
+
+Admin lists use bounded container grids:
+
+- one flexible fill column;
+- fixed total table width;
+- compact action/status/count columns;
+- resizable text/date columns;
+- no intrinsic content growth;
+- sticky headers where needed;
+- server pagination for audit.
+
+## Deferred Work
+
+- DataGrid sizing and resize behavior remains explicitly deferred. The current
+  bounded-grid contract above is binding, but further layout changes should be
+  handled as a dedicated, isolated UI debt item because the component is shared
+  and brittle.
+- real SMTP/IMAP test-bed verification and operator runbook;
+- recipient import with column mapping;
+- session/device revocation UI;
+- backup/restore, monitoring, and update procedures;
+- DSAR workflows and evidence bundle verifier;
+- campaign ownership transfer workflow;
+- policy impact analysis before delete/disable/unshare/change;
+- LDAP/OIDC/SAML provisioning;
+- destructive tenant erasure orchestration.

docs/GOVOPLAN_MASTER_ROADMAP.md

@@ -0,0 +1,663 @@
+# GovOPlaN Master Roadmap
+
+This roadmap is the durable product north star and sequencing guide for
+GovOPlaN as a modular platform for administrative operations. It keeps the
+product moving without turning every possible public-sector need into an
+immediate implementation track.
+
+Use this document for product direction, sequencing, and module routing. Issues
+are the active backlog; this document is durable planning context and should be
+mirrored to the Gitea wiki.
+
+## Product Thesis
+
+GovOPlaN should become a configurable operations platform for public
+institutions. It should help an institution model real administrative
+procedures, connect existing systems, keep durable evidence, and explain the
+configured system to users.
+
+The goal is not to replace every existing system. GovOPlaN should connect
+existing systems, provide better workflows where the current landscape is weak,
+and make administrative processes configurable, auditable, and reusable.
+
+The product should first provide a reliable administrative spine:
+
+- identities, roles, tenants, policy, audit, and governance
+- forms, files, cases, workflow, tasks, templates, and records
+- postboxes, notifications, mail, portal, appointments, and booking
+- identity trust, role-bound postboxes, and eventually encrypted administrative
+  communication
+- configuration packages that assemble modules into repeatable procedures
+- docs that explain the configured system, not the full theoretical product
+
+Domain modules should come after the spine can run a reference procedure end to
+end.
+
+The platform should be a governance-capable runtime for modules, connectors,
+configuration, and administrative decisions. The kernel must stay free of domain
+semantics while still providing the contracts needed for modules to explain what
+they do, what they require, which effects they create, and how operators can
+verify or reverse those effects.
+
+## Design Principles
+
+- Modules must stay independently installable, enableable, and disableable.
+- Cross-module behavior should use core-mediated capabilities, commands,
+  events, DTOs, and UI contribution points rather than direct imports.
+- Configuration packages should turn installed modules into concrete, reusable
+  administrative processes.
+- Operators should be able to configure the platform through the UI.
+- Every powerful configuration path needs preflight, preview, audit, rollback,
+  RBAC, and policy checks.
+- Context, decision, consequence, and traceability must be visible together for
+  consequential actions. The full doctrine lives in
+  `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`.
+- Automation must use governed action/effect contracts, not hidden side
+  effects. The first automation layer is defined in
+  `ACTION_EFFECT_AUTOMATION_LAYER.md` and should start in `govoplan-workflow`
+  unless a separate automation module becomes justified.
+- Encrypted postboxes are a strategic target. Early postbox, access, and
+  identity-trust contracts should stay compatible with the E2EE architecture in
+  `POSTBOX_E2EE_ARCHITECTURE.md`.
+- Integration should be a first-class product path: connect to existing
+  systems, consume their data, and publish governed outputs back to them.
+- GovOPlaN should scale from a small local installation to a larger deployment
+  with separately scalable web, API, worker, storage, and database components.
+
+## User Experience Direction
+
+GovOPlaN should expose the full power of the platform without forcing
+non-technical users to face every field, flag, and internal representation at
+once. The default experience should feel guided, explainable, and calm. Expert
+depth should remain available, but it should be layered behind deliberate
+interaction patterns.
+
+Core UX rules:
+
+- Use progressive disclosure. Common decisions stay visible; advanced,
+  hazardous, or rarely used options live in collapsed panels, secondary steps,
+  or explicit advanced areas.
+- Do not use raw JSON as the primary configuration UI. Every configurable value
+  should have an appropriate control, validation, and plain-language help.
+  Import/export and diagnostics may show JSON as a secondary artifact.
+- Prefer guided flows over option dumps. Connector setup, package import,
+  module installation, policy changes, and destructive operations should use
+  wizards that explain what is happening, why it matters, and what will happen
+  next.
+- Discover values when the system can infer them. For example, a Nextcloud file
+  connection should start with the base URL, discover the WebDAV endpoint, and
+  fill technical fields for review instead of asking the user to know them
+  upfront.
+- Make explanations always available without making every screen verbose.
+  Inline helper text should be short; richer explanations should be reachable
+  through expandable help, tooltips, side panels, or review steps.
+- Explain blocked actions in actionable language. A disabled control or failed
+  step should say what is missing, who can fix it, and where to go, for example
+  "A system administrator must allow this provider" or "Configure the provider
+  in Settings > File Providers before linking a folder here."
+- Reuse visual language and placements consistently. Similar configuration,
+  policy, connection, credential, review, and confirmation flows should share
+  components, button placement, modal behavior, problem lists, and empty/error
+  states.
+- Use modals and step flows for focused creation/editing where they reduce page
+  clutter. Reserve large always-open pages for overview, comparison, and
+  repeated administration work.
+- Treat diagnostics as product UX. Validation results, preflight blockers,
+  policy explanations, permission denials, and missing capabilities should be
+  understandable to a non-technical operator before exposing internal details.
+
+This is a product quality gate. New admin/configuration surfaces should not be
+considered complete if they expose all options at once, require JSON editing,
+hide why an action is unavailable, or use a one-off layout where a shared
+pattern exists.
+
+## Focus Rules
+
+1. Build one reference journey per wave.
+2. Do not implement a module because the repository exists.
+3. Do not add module-to-module imports for optional behavior.
+4. Every new domain module must justify its own semantics beyond `cases`,
+   `workflow`, `tasks`, `forms`, and `files`.
+5. Prefer connector first when an external specialist system is likely to remain
+   the system of record.
+6. Keep active work in Gitea issues; keep durable context in docs and synced
+   wiki pages.
+7. A module moves from scaffold to implementation only when it has an owner,
+   reference journey, boundary notes, capability contracts, and testable MVP.
+
+## Capability Map
+
+| Capability | Likely owner |
+| --- | --- |
+| Public application entry point | `govoplan-portal` |
+| Structured forms and validation | `govoplan-forms` |
+| Uploaded files and managed storage | `govoplan-files` |
+| Case record and lifecycle | `govoplan-cases` |
+| Workflow transitions and automation | `govoplan-workflow` |
+| Action/effect catalogue and automation runner | first `govoplan-workflow`; possible future `govoplan-automation` if it outgrows workflow |
+| Internal work queues and tasks | `govoplan-tasks` |
+| Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` |
+| Postbox, email, and notifications | `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications` |
+| Identity trust, device keys, and encrypted postbox key contracts | `govoplan-identity-trust`, `govoplan-access`, `govoplan-postbox` |
+| Service directory/catalog | `govoplan-portal` |
+| Permit/document generation | `govoplan-templates`, `govoplan-dms` |
+| Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` |
+| Roles, permissions, tenants, policy, audit | `govoplan-access`, `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` |
+| External software integration | `govoplan-connectors` |
+| Recurring extraction and transformation | possible future `govoplan-datasources`, possible future `govoplan-dataflow` |
+| Reports, BI, and management visibility | `govoplan-reporting` |
+
+## Configuration And Safety Target
+
+The long-term target is that operators configure the platform through the UI
+instead of editing files for normal operation.
+
+UI-managed configuration should include:
+
+- module installation, enablement, lifecycle state, and health
+- tenants, users, groups, roles, policies, and permissions
+- connectors, credentials, secret references, and external service tests
+- workflows, forms, templates, task queues, schedules, and notifications
+- configuration package import/export and environment-specific data collection
+- retention, audit, privacy, maintenance mode, and safety controls
+- deployment-visible settings such as public URLs, mail senders, storage
+  profiles, queues, and worker capabilities
+
+Safety controls should include dry-run plans, field-level validation, policy
+explanations, two-person approval for destructive changes, versioned
+configuration history, rollback paths, audit events, and maintenance-mode
+guards.
+
+The initial safety metadata contract lives in
+`govoplan_core.core.configuration_safety`. It classifies known configuration
+fields as UI-managed or deployment-managed, assigns risk levels, marks secret
+handling as reference-only or env-only, and declares dry-run, policy
+explanation, audit, approval, rollback-history, maintenance-mode, and RBAC
+requirements. Admin UI editors should consume this metadata before exposing
+powerful settings.
+
+The initial executable guardrail path is `plan_configuration_change(...)`,
+exposed through:
+
+- `GET /api/v1/admin/configuration-safety`
+- `POST /api/v1/admin/configuration-safety/plan`
+
+The planner reports missing scopes, dry-run requirements, maintenance-mode
+requirements, two-person approval status, secret-reference violations,
+rollback-history requirements, policy explanations, and audit event names before
+an editor applies a high-impact configuration change.
+
+## Reference Journeys
+
+The roadmap should be driven by three journeys.
+
+### Journey 1: Permit To Payment
+
+This is the primary public-administration journey.
+
+1. A person applies for a permit through the public portal.
+2. The applicant uploads required files and submits structured form data.
+3. Submission creates a case, a workflow instance, and an internal task.
+4. Completing the task creates a postbox message, a notification, and an email
+   notification with an appointment proposal.
+5. The applicant accepts an appointment, which updates the calendar and the
+   workflow state.
+6. During the appointment, the case is opened and the permit is generated from
+   a governed template.
+7. The payment is processed and linked to the case and accounting handoff.
+8. The permit, payment evidence, communication history, audit trail, retention
+   state, and records evidence remain available according to policy.
+
+This journey proves the platform can coordinate modules without core knowing
+module internals.
+
+### Journey 2: Training To Certificate
+
+This is the best university-administration and internal-administration journey.
+
+1. Course or training offer is planned.
+2. Room, trainer, resource, and capacity are booked.
+3. Participants register or are assigned.
+4. Attendance is tracked.
+5. Certificate or participation confirmation is issued.
+6. Evidence remains available through records, files, audit, and docs.
+
+This journey keeps `booking`, `resources`, `learning`, and `certificates`
+focused instead of becoming broad ERP replacements.
+
+### Journey 3: Report To Resolution
+
+This is the internal operations and municipal issue-reporting journey.
+
+1. A person reports an issue.
+2. The issue is triaged into helpdesk, facilities, assets, or a case.
+3. Work is assigned, tracked, and escalated.
+4. Evidence, communication, and status updates are preserved.
+5. Reports show workload, SLA, recurring problems, and completion.
+
+This journey prevents `helpdesk`, `issue-reporting`, `facilities`, and `assets`
+from becoming disconnected ticket silos.
+
+## Roadmap Waves
+
+### Wave 0: Platform Spine
+
+Goal: make the platform safe to configure and extend.
+
+Refine:
+
+- `govoplan-core`: module discovery, capabilities, events, migrations, release
+  catalog, configuration package runtime, WebUI shell.
+- `govoplan-access`: identities, sessions, API keys, users, groups, roles,
+  memberships, function assignments, delegation, RBAC decisions.
+- `govoplan-tenancy`: tenant and organizational-unit boundaries.
+- `govoplan-identity-trust`: initial trust contracts for device keys, public key
+  directory, assurance, and later encrypted postbox key access.
+- `govoplan-policy`: policy sources, policy decisions, retention inputs.
+- `govoplan-audit`: audit sink, audit routes, trace context, retention
+  cooperation.
+- `govoplan-admin`: UI-managed configuration with preflight, rollback, audit,
+  and approval controls.
+- `govoplan-dashboard`: configurable user home assembled from module-provided
+  widgets, with core providing only a minimal fallback when the module is absent.
+- `govoplan-docs`: configured-system documentation and evidence-aware help.
+- `govoplan-ops`: deployment profiles, health checks, worker split, sizing
+  assumptions.
+
+Do not expand domain scope in this wave. The output is a dependable platform
+surface for later modules.
+
+Exit criteria:
+
+- module enablement and capability lookup are stable
+- configuration package preflight works for at least one simple package
+- audit and policy decisions are visible in admin flows
+- access distinguishes identity, account, function, role, and right in durable
+  contracts
+- action/effect automation contracts are specified before hidden side effects
+  spread across modules
+- docs can show installed/enabled modules and configured routes
+
+### Wave 1: Permit-To-Payment MVP
+
+Goal: one complete public-administration process.
+
+Create or refine in this order:
+
+1. `govoplan-forms-runtime`: form submissions, drafts, validation, attachments,
+   and submission evidence.
+2. `govoplan-portal`: public authenticated and unauthenticated entry points.
+3. `govoplan-files`: upload, evidence links, file spaces, and permissioned
+   access.
+4. `govoplan-cases`: case record, status, assignments, deadlines, and case
+   evidence.
+5. `govoplan-workflow`: state machine, transitions, commands, and module
+   handoff.
+6. `govoplan-tasks`: work queues, assignments, due dates, and follow-ups.
+7. `govoplan-templates`: permit/decision document generation.
+8. `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications`: applicant and
+   internal communication, with the postbox model compatible with later E2EE
+   and role-bound access.
+9. `govoplan-calendar`, `govoplan-appointments`, `govoplan-booking`: appointment
+   or booking handoff for the reference process.
+10. `govoplan-payments`, `govoplan-ledger`, `govoplan-xrechnung`: payment
+    capture, payment evidence, and accounting/e-invoice handoff.
+
+Exit criteria:
+
+- a permit-to-payment package can be installed in a local demo
+- every step has audit evidence
+- every module integration uses capabilities, events, or DTOs
+- user-facing documentation describes only the configured process
+
+### Wave 2: Booking And Resource Operations
+
+Goal: make time, capacity, and resource allocation a reusable product area.
+
+Create or refine in this order:
+
+1. `govoplan-booking`: booking rules, capacity, quotas, waitlists, cancellation,
+   attendance, no-shows, and approvals.
+2. `govoplan-resources`: rooms, equipment, vehicles, counters, labs, capacity,
+   availability, and maintenance blocks.
+3. `govoplan-calendar`: event and availability integration.
+4. `govoplan-appointments`: appointment-specific booking surfaces.
+5. `govoplan-facilities`: buildings, rooms, maintenance, access zones,
+   inspections, and defects.
+6. `govoplan-assets`: inventory, assignment, lifecycle, maintenance, and handover
+   evidence.
+
+Reference journey: reserve a room/resource for a training or appointment and
+preserve all booking evidence.
+
+Exit criteria:
+
+- bookable resources are not hardcoded into appointments
+- booking decisions are explainable and auditable
+- resources can be blocked by maintenance or facility status
+
+### Wave 3: Training And Certificates
+
+Goal: support university-style and internal public-sector training without
+building a full learning-management system first.
+
+Create or refine in this order:
+
+1. `govoplan-learning`: course planning, course booking, participant lists,
+   trainers, attendance, evaluations, and learning records.
+2. `govoplan-certificates`: participation confirmations, certificates,
+   verification, revocation, and evidence links.
+3. `govoplan-booking`, `govoplan-resources`, `govoplan-calendar`: reuse booking
+   and room/resource allocation.
+4. `govoplan-templates`, `govoplan-files`, `govoplan-records`: certificate
+   generation and durable retention.
+
+Reference journey: plan a course, book resources, register participants, track
+attendance, and issue a certificate.
+
+Exit criteria:
+
+- attendance can produce certificate eligibility
+- certificates can be verified later
+- course operations do not depend on university-specific assumptions
+
+### Wave 4: Report-To-Resolution Operations
+
+Goal: cover internal support and public issue reporting.
+
+Create or refine in this order:
+
+1. `govoplan-issue-reporting`: public/internal reports, categories, intake,
+   location, evidence, and triage.
+2. `govoplan-helpdesk`: service desk tickets, queues, SLAs, assignments,
+   escalation, and resolution evidence.
+3. `govoplan-facilities` and `govoplan-assets`: issue handoff to maintenance or
+   asset lifecycle.
+4. `govoplan-cases`, `govoplan-workflow`, `govoplan-tasks`: escalation into
+   formal administrative matters.
+5. `govoplan-reporting`: workload, SLA, recurring defects, and status reports.
+
+Reference journey: report a facility issue, triage it, assign work, resolve it,
+and report recurring defects.
+
+Exit criteria:
+
+- issue reporting is not just a generic form inbox
+- helpdesk tickets can remain lightweight unless formal case handling is needed
+- operational metrics exist without custom SQL
+
+### Wave 5: Records, DMS, Transparency
+
+Goal: make evidence legally and organizationally durable.
+
+Create or refine in this order:
+
+1. `govoplan-dms`: document lifecycle, collaboration, versions, locks, approvals,
+   and DMS connectors.
+2. `govoplan-records`: file plans, classification, retention schedules, disposal
+   holds, archive handoff, and records evidence.
+3. `govoplan-policy` and `govoplan-audit`: retention policy, legal hold, audit
+   traceability.
+4. `govoplan-search`: permissioned cross-module discovery.
+5. `govoplan-transparency`: FOI/public-records requests, redaction, publication,
+   and disclosure evidence.
+
+Reference journey: close a case, classify records, apply retention, and answer a
+transparency request.
+
+Exit criteria:
+
+- files, documents, and records are not treated as the same concept
+- transparency disclosure can redact and explain evidence
+- retention and archive handoff are policy-governed
+
+### Wave 6: Finance, Procurement, Contracts, Grants
+
+Goal: cover the back-office procedures around spending, obligations, funding,
+and revenue without replacing a finance system too early.
+
+Create or refine in this order:
+
+1. `govoplan-procurement`: purchase requests, approvals, vendor comparison,
+   tender references, goods receipt, and handoff.
+2. `govoplan-contracts`: contract register, obligations, renewals, reminders,
+   and responsible units.
+3. `govoplan-grants`: funding programs, applications, eligibility, awards,
+   milestones, claims, and reporting duties.
+4. `govoplan-payments`, `govoplan-ledger`, `govoplan-xrechnung`: payment,
+   accounting, and e-invoice handoff.
+5. `govoplan-erp`: integration with the actual system of record, not a full ERP
+   replacement unless later justified.
+
+Reference journey: purchase or grant approval through obligation tracking and
+financial handoff.
+
+Exit criteria:
+
+- ERP remains an integration point unless GovOPlaN must own semantics
+- contracts and grants produce obligations, deadlines, and reporting tasks
+- financial evidence links back to cases, files, and audit
+
+### Wave 7: Institutional Governance And Participation
+
+Goal: support public bodies, municipalities, ministries, and universities in
+formal coordination.
+
+Create or refine in this order:
+
+1. `govoplan-committee`: committees, boards, councils, agendas, minutes,
+   decisions, voting, and follow-up tasks.
+2. `govoplan-consultation`: hearings, public consultations, stakeholder
+   feedback, formal comments, response matrices, and publication workflows.
+3. `govoplan-campaign`: communication campaigns, recipients, templates, review,
+   sending control, and reports.
+4. `govoplan-addresses`: persons, organizations, contacts, distribution lists,
+   and recipient import/export.
+5. `govoplan-portal` and `govoplan-transparency`: public participation and
+   publication surfaces.
+
+Reference journey: prepare a committee decision, publish consultation material,
+collect feedback, document the decision, and assign follow-up tasks.
+
+Exit criteria:
+
+- decisions create durable tasks and records
+- consultations can publish evidence without exposing restricted material
+- campaign and address behavior stays optional and capability-based
+
+### Wave 8: Integration, Data, And Reporting
+
+Goal: connect the platform to real institutional landscapes.
+
+Refine:
+
+- `govoplan-connectors`: integration catalog, connector metadata, adapter
+  lifecycle, test harnesses.
+- `govoplan-idm`, `govoplan-identity-trust`: identity provider, directory, and
+  assurance integration.
+- `govoplan-fit-connect`, `govoplan-xoev`, `govoplan-xta-osci`: public-sector
+  transport and standards integration.
+- `govoplan-reporting`: operational reporting, scheduled outputs, exports, and
+  dashboard data.
+- `govoplan-search`: permissioned cross-module discovery.
+
+Create only when justified:
+
+- `govoplan-datasources`: source catalog, connection profiles, schema discovery,
+  freshness, provenance.
+- `govoplan-dataflow`: transformations, validation, lineage, scheduled runs,
+  publication outputs.
+- `govoplan-projects`: only if OpenProject connectors and existing cases/tasks
+  cannot cover the required semantics.
+
+Reference journey: monthly data extraction, transformation, validation, approval,
+publication, and reporting.
+
+Recurring extraction/transformation should start as a configuration package
+across connectors, files, workflow, reporting, and templates. The package should
+register sources, declare schemas, define mapping/validation versions, schedule
+runs, produce previewable diffs, write governed outputs, and preserve lineage,
+hashes, operator actions, and audit evidence. Create `govoplan-datasources` or
+`govoplan-dataflow` only after this work exposes repeated contracts that do not
+belong to existing modules.
+
+Exit criteria:
+
+- connector catalog exists before building many adapters
+- dataflow is created only after recurring transformation becomes product
+  behavior
+- reporting consumes governed sources with provenance
+
+## Implementation Gates
+
+Before a module receives implementation work, it needs:
+
+- one reference journey step it owns
+- ownership and boundary notes
+- initial manifest and permission list
+- capability contracts or API DTOs
+- audit and policy expectations
+- Gitea issues for MVP tasks
+- docs page that can sync to the wiki
+- focused tests that can run from the core environment
+
+Before a module becomes release-included, it needs:
+
+- installable Python package metadata where applicable
+- WebUI package metadata where applicable
+- module manifest entry point
+- release catalog entry
+- smoke test or permutation test
+- no required imports from optional modules
+
+## Priority Order Summary
+
+1. Stabilize the platform spine.
+2. Deliver permit-to-payment MVP.
+3. Build booking and resource operations.
+4. Add learning and certificates.
+5. Add issue reporting and helpdesk.
+6. Add records, DMS, search, and transparency.
+7. Add procurement, contracts, grants, and finance handoff.
+8. Add committee and consultation workflows.
+9. Expand integration, dataflow, reporting, and operations.
+
+## Deliberate Deferrals
+
+Defer these until a reference journey proves the need:
+
+- full ERP replacement
+- native project management beyond connector support
+- broad BI/dataflow platform
+- every possible public-sector protocol adapter
+- rich LMS behavior beyond training administration
+- full qualified digital signing/trust services beyond the identity-trust and
+  encrypted-postbox contracts needed for early architecture safety
+- mobile apps
+- AI assistants embedded into workflows
+
+These may become important, but they should not distract from the first complete
+administrative journeys.
+
+## Module And Integration Routing
+
+This table maps current module and integration ideas to existing GovOPlaN
+repositories or to explicit missing-module decisions.
+
+| Idea | Owner | Tracking |
+| --- | --- | --- |
+| Government operations backbone reference model | `govoplan-core` | `add-ideas/govoplan-core#213` |
+| Permit-to-payment configuration package | `govoplan-core` plus participating modules | `add-ideas/govoplan-core#214` |
+| Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `add-ideas/govoplan-core#218` |
+| Access as a module | `govoplan-access` | `add-ideas/govoplan-access#7` |
+| Interface ethics and decision-consequence doctrine | `govoplan-core` plus all UI-owning modules | `add-ideas/govoplan-core#227` |
+| Action/effect automation layer | first `govoplan-workflow`; possible future `govoplan-automation` | `add-ideas/govoplan-workflow#1` |
+| E2EE role/function postbox architecture | `govoplan-postbox`, `govoplan-identity-trust`, `govoplan-access`, `govoplan-policy`, `govoplan-audit` | `add-ideas/govoplan-postbox#15`, `add-ideas/govoplan-identity-trust#1` |
+| Identity, account, function, role, right semantic model | `govoplan-access` | `add-ideas/govoplan-access#9` |
+| Role-based service directory/catalog | `govoplan-portal` | `add-ideas/govoplan-portal#1` |
+| Unified inbox across tasks, postbox, notifications, and portal | `govoplan-core` coordination plus owning modules | `add-ideas/govoplan-tasks#1`, `add-ideas/govoplan-notifications#1` |
+| OpenProject API / project management connector | `govoplan-connectors` | `add-ideas/govoplan-connectors#1` |
+| Native project-management module decision | connector-first through `govoplan-connectors`; no native project module yet | `add-ideas/govoplan-core#196`, `add-ideas/govoplan-connectors#1` |
+| Datasources for databases, CSV, files, APIs | no repository yet; start with connectors/files/reporting and create `govoplan-datasources` only after the first package proves shared source-catalog ownership | `add-ideas/govoplan-core#197` |
+| Dataflow for pipelines, BI, publication | no repository yet; start with workflow/reporting/connectors and create `govoplan-dataflow` only after repeated pipeline/lineage contracts emerge | `add-ideas/govoplan-core#198` |
+| Monthly datasource and transformation workflows | first as configuration package across connectors, files, workflow, reporting, and templates | `add-ideas/govoplan-core#216` |
+| Templates for letters, emails, forms, reports | `govoplan-templates`, separate from reporting | `add-ideas/govoplan-core#190`, `add-ideas/govoplan-templates#1` |
+| Reporting and BI | `govoplan-reporting`, separate from templates | `add-ideas/govoplan-core#190`, `add-ideas/govoplan-reporting#1` |
+| File connectors: Nextcloud, Seafile, SMB, NFS | `govoplan-files` | `add-ideas/govoplan-files#15` |
+| Public-sector software integration catalogue | `govoplan-connectors` with core strategy index | `add-ideas/govoplan-core#191`, `add-ideas/govoplan-connectors#2` |
+| Public-sector integration landscape catalogue | `govoplan-connectors` with core tracking | `add-ideas/govoplan-core#215` |
+| Cases module concept | `govoplan-cases` | `add-ideas/govoplan-core#174` |
+| Workflow module concept | `govoplan-workflow` | `add-ideas/govoplan-core#175` |
+| Connectors module concept | `govoplan-connectors` | `add-ideas/govoplan-core#176` |
+| Adrema-style address and distribution-list management | `govoplan-addresses` | `add-ideas/govoplan-addresses#1` |
+| Consume sources and become a governed source | `govoplan-connectors` plus possible future `govoplan-dataflow` | `add-ideas/govoplan-connectors#3`, `add-ideas/govoplan-core#198` |
+| Governed connector configuration, dry-run, and simulation runtime | `govoplan-connectors` | `add-ideas/govoplan-connectors#6` |
+| Terminfindung and meeting scheduling polls | `govoplan-scheduling`; calendar primitives remain in calendar | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-scheduling#1` |
+| Terminplaner and calendar primitives | `govoplan-calendar` | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-calendar#1` |
+| Terminbuchung appointment booking | `govoplan-appointments` | `add-ideas/govoplan-core#193`, `add-ideas/govoplan-appointments#1` |
+| Collaborative documents | `govoplan-dms` | `add-ideas/govoplan-dms#1` |
+| Forms | `govoplan-forms` for definitions and `govoplan-forms-runtime` for submissions/runtime behavior | `add-ideas/govoplan-core#194`, `add-ideas/govoplan-forms#1` |
+| RSS consume and emit | `govoplan-connectors` | `add-ideas/govoplan-connectors#4` |
+| LDAP, Active Directory, OpenDesk identity | `govoplan-idm` | `add-ideas/govoplan-idm#1` |
+| OpenDesk stack integration map | integration profile across IDM/access, mail/calendar, files/DMS, and connectors; not a monolithic module | `add-ideas/govoplan-core#195`, `add-ideas/govoplan-connectors#5` |
+| Open-Xchange mail/groupware | `govoplan-mail` | `add-ideas/govoplan-mail#5` |
+| Open-Xchange calendar | `govoplan-calendar` | `add-ideas/govoplan-calendar#2` |
+| Scalability profiles and autoscaling readiness | `govoplan-ops`, `govoplan-core` | `add-ideas/govoplan-core#217` |
+| Hardware sizing matrix and requirements calculator | `govoplan-ops`, `govoplan-core` | `add-ideas/govoplan-core#219` |
+| Collaboration suite integration strategy | `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow`, `govoplan-tasks`, `govoplan-appointments`, `govoplan-calendar` | `add-ideas/govoplan-core#220` |
+| Install/runtime configuration contract | `govoplan-core`, later `govoplan-ops` | `add-ideas/govoplan-core#19` |
+| Installer/deployment operator flow | `govoplan-core`, later `govoplan-ops` | `add-ideas/govoplan-core#26` |
+| Production-like deployment documentation | `govoplan-core`, later `govoplan-ops` | `add-ideas/govoplan-core#28` |
+
+Boundary rationale lives in `MODULE_ARCHITECTURE.md`. Current decisions:
+
+- templates and reporting are separate modules
+- RSS/source consume-publish starts in connectors; datasources/dataflow are not
+  repositories yet
+- calendar, scheduling, and appointments are three separate modules
+- forms definitions and forms runtime are separate responsibilities
+- OpenDesk is an integration profile across modules, not a monolithic module
+- OpenProject is connector-first; no native projects module yet
+- public-sector integration strategy stays in core; executable catalogue work
+  lives in connectors
+- encrypted postbox and identity-trust are strategic contracts, not mail-module
+  behavior
+- automation starts as workflow-owned action/effect execution and may split into
+  a dedicated module only after the runner becomes broader than workflow
+
+The following modules are intentionally not created yet:
+
+- `govoplan-datasources`
+- `govoplan-dataflow`
+- `govoplan-projects`
+
+Create a repository only after a concrete implementation package proves that
+existing connector, files, reporting, workflow, or task ownership is too narrow.
+
+Core keeps the strategy index in
+`PUBLIC_SECTOR_INTEGRATION_STRATEGY.md`: integration postures, default
+ownership, and prioritization rules. `govoplan-connectors` owns the detailed
+target inventory and connector entry shape in
+`govoplan-connectors/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md`.
+
+Release composition and tag-only repository handling are documented in
+`RELEASE_DEPENDENCIES.md`.
+
+## Next Practical Work
+
+The next planning step should create or update Gitea issues for Wave 0 and Wave
+1 only. Later waves should stay as roadmap context until the permit-to-payment
+MVP is demonstrable.
+
+Recommended immediate issue buckets:
+
+- platform spine hardening
+- configuration package preflight and rollback
+- forms-runtime MVP
+- portal submission MVP
+- cases/workflow/tasks integration MVP
+- template-generated decision document
+- postbox/notification handoff
+- appointment/booking handoff
+- payment evidence handoff
+- configured documentation for the reference process

docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md

@@ -0,0 +1,102 @@
+# GovOPlaN Interface Ethics And Design Doctrine
+
+This document captures the product-level design doctrine for GovOPlaN. It is
+more durable than an individual screen design and should guide admin,
+configuration, workflow, policy, portal, and operational UI decisions.
+
+GovOPlaN is meant to support administrative responsibility. The interface must
+therefore make context, decision, consequence, and traceability visible enough
+that users can act deliberately instead of being pushed through opaque
+automation.
+
+## Core Doctrine
+
+1. Context, decision, and consequence belong together.
+2. Decisions should not silently happen.
+3. Transparency comes before convenience when rights, duties, records, money,
+   access, or legal effects are involved.
+4. Explicit state is preferable to implicit state.
+5. Navigation is not consent.
+6. Responsibility cannot be delegated to the system.
+7. Traceability is part of the action, not a later reporting feature.
+8. Context loss is a product defect.
+
+These rules do not mean every screen should become verbose. They mean the
+interface must expose the right explanation at the moment of decision and keep
+technical detail available without making it the default surface.
+
+## Decision Surface Contract
+
+Any action that changes records, rights, policies, retention, communication,
+payments, external systems, or workflow state should answer these questions
+before execution:
+
+- What object, person, organization, or process is affected?
+- Which authority or role allows the actor to do this?
+- What will change immediately?
+- What downstream effects may happen?
+- Can the action be undone, superseded, or only corrected later?
+- What evidence or audit entry will be created?
+- Which policy, configuration, or missing capability blocks the action?
+- Who can resolve a blocker?
+
+The answer may be shown through inline labels, a review step, a side panel, a
+problem list, or a confirmation dialog. The important point is that consequence
+and responsibility are not hidden behind a generic submit button.
+
+## Contestability
+
+Administrative decisions are often contestable or reviewable. GovOPlaN should
+therefore preserve the path from input to decision:
+
+- source data and attachments
+- workflow state and task assignment
+- policy decisions and source path
+- actor and delegation context
+- generated document/template version
+- external handoff result
+- notification or postbox delivery evidence
+- retention and record classification state
+
+Where a user sees a decision, they should be able to reach the provenance that
+explains how the system got there. This is especially important for denials,
+locks, calculated defaults, generated documents, payment state, retention
+state, and access decisions.
+
+## Anti-Patterns
+
+Avoid these patterns in GovOPlaN interfaces:
+
+- Magical buttons that execute multiple side effects without preview.
+- Process tunnels that hide where the user is in an administrative procedure.
+- Silent automation that changes external systems without an audit-visible
+  command record.
+- Friendly hiding that removes complexity at the cost of obscuring authority,
+  consequence, or accountability.
+- Disabled controls without actionable explanation.
+- Configuration screens that ask users to edit raw JSON as the normal path.
+
+## Automation Rule
+
+Automation must use the same governed action surface as a human actor. The
+system may execute actions as a system actor, but it must still run through
+policy checks, capability contracts, audit, idempotency, and failure handling.
+
+When an automated decision is not clear, GovOPlaN should create a manual
+exception, task, or review item instead of guessing silently.
+
+## Relationship To UI Components
+
+Shared components should make this doctrine easy to follow:
+
+- preflight and problem-list components for blockers
+- policy source path and effective decision displays
+- action review panels for consequence preview
+- audit/provenance links on decision outputs
+- guided dialogs for risky configuration
+- disabled-action explanations with actor and next step
+- confirmation dialogs that distinguish reversible, corrective, and destructive
+  actions
+
+The UI/UX decision ledger defines concrete implementation rules. This doctrine
+defines why those rules exist.

docs/POLICY_CONTRACTS.md

@@ -0,0 +1,115 @@
+# GovOPlaN Policy Contracts
+
+GovOPlaN has several policy families that are moving out of core into owning
+modules. The shared kernel contract keeps their decision and provenance shape
+consistent while each module still owns its domain rules.
+
+## Current Policy Inventory
+
+| Policy area | Current owner | Runtime surface | Notes |
+| --- | --- | --- | --- |
+| Privacy retention | `govoplan-policy` implementation and routes, with compatibility helpers in core | `/api/v1/admin/privacy-retention/policies/{scope}` and `/explain`; capability `policy.privacyRetention` | System, tenant, user, group, and campaign sources merge into the effective retention policy. Parent locks block lower-level widening. |
+| Mail profile policy | `govoplan-mail` | `/api/v1/mail/policies/{scope}` | Uses the same source-step path format for system, tenant, owner, and campaign provenance. |
+| RBAC/access policy | `govoplan-access` | access capabilities in `govoplan_core.core.access` | Permission decisions should use access capability contracts. Explain responses should adopt `PolicyDecision` when an API-level explanation is added. |
+| Governance defaults | `govoplan-admin` plus `govoplan-access` materializer | admin settings, governance template routes, access materialization capability | System governance can block tenant-local groups, roles, and API keys. |
+| Delegation and ownership policy | access/campaign/mail/files modules | capability checks and owner-scoped APIs | Source provenance should use this contract when policies become externally explainable. |
+
+## Policy Decision
+
+The shared DTO lives in `govoplan_core.core.policy.PolicyDecision`.
+
+```json
+{
+  "allowed": false,
+  "reason": "Parent retention policy locks lower-level changes.",
+  "source_path": [
+    {
+      "scope_type": "system",
+      "scope_id": null,
+      "path": "system",
+      "label": "System",
+      "applied_fields": ["allow_lower_level_limits"],
+      "policy": {}
+    }
+  ],
+  "requirements": ["raw_campaign_json_retention_days"],
+  "details": {
+    "blocked_fields": ["raw_campaign_json_retention_days"]
+  }
+}
+```
+
+`allowed` is the effective answer for the checked action. `reason` is a stable,
+human-readable summary. `source_path` lists the policy sources that explain the
+answer. `requirements` lists machine-readable blockers or prerequisites, and
+`details` carries domain-specific structured context.
+
+Every source step should be concrete enough for an operator to understand the
+decision without knowing internal merge rules. Use real scope labels such as
+`System`, `Tenant`, `Owner user`, `Group`, or a campaign/profile name. Include
+the stable `path`, the fields applied by that step, and the local policy
+fragment that caused them. This lets UIs render explanations like
+`System: Allow > Tenant: Deny without override` without additional lookups.
+If a policy family cannot expose the full local fragment for security reasons,
+it must still include a redacted structured value that identifies the applied
+field and the effective allow/deny or lock state.
+
+## Source Path Format
+
+Policy source paths are stable string identifiers for provenance steps:
+
+- `system`
+- `<scope_type>:<url-encoded-scope-id>`
+
+Supported scope types are `system`, `tenant`, `user`, `group`, and `campaign`.
+Examples:
+
+- `tenant:4a45b4fe-1d86-43ce-9d10-6022333f4d4b`
+- `campaign:campaign%2Fwith%20space`
+
+Use `policy_source_path()` and `parse_policy_source_path()` instead of building
+or splitting these strings manually.
+
+## Retention Explain Endpoint
+
+`GET /api/v1/admin/privacy-retention/policies/{scope_type}/explain` returns:
+
+- `scope_type` and optional `scope_id`
+- `decision`, using the shared `PolicyDecision` shape
+- `effective_policy`
+- optional `parent_policy`
+- `effective_policy_sources`
+- `parent_policy_sources`
+- `blocked_fields`
+
+The endpoint is read-only. Enforcement remains in the existing policy write
+path. For lower-level scopes, `blocked_fields` is derived from the parent
+policy's `allow_lower_level_limits`; clients can use it to disable local
+controls before attempting a write.
+
+The retention implementation lives in `govoplan-policy`
+(`govoplan_policy.backend.retention`). Core keeps
+`govoplan_core.privacy.retention` only as a compatibility facade for older
+imports. Effective/scoped retention behavior dispatches through the
+`policy.privacyRetention` capability; core does not import policy implementation
+code as a hidden fallback when the module is disabled or no runtime is active.
+New backend code should import policy-owned retention behavior from
+`govoplan-policy` or request the capability, not add new implementation logic
+to core.
+
+## Frontend Contract
+
+Policy UIs must:
+
+- render effective source provenance when `effective_policy_sources` is present
+- display a field-level path when the source data is shown next to a specific
+  setting, using concrete source labels and stop at the first non-overridable
+  deny/lock
+- disable local field controls when the parent policy sets that field's
+  lower-level limit to `false`
+- avoid sending locked fields or re-enable attempts in save payloads
+- show inherited values separately from local overrides
+
+The core WebUI helper `privacyRetentionParentAllowsField()` centralizes the
+field-lock decision used by the retention editor and its lightweight module
+tests.

docs/POSTBOX_E2EE_ARCHITECTURE.md

@@ -0,0 +1,134 @@
+# Postbox End-To-End Encryption Architecture
+
+This document records the strategic encryption target for GovOPlaN postboxes.
+It does not require the first postbox implementation to ship full E2EE, but it
+defines the architecture so early data models and APIs do not make the stronger
+model impossible.
+
+The core principle is that a postbox can become a trusted administrative
+communication channel without requiring the server to see plaintext content.
+The server may route, store, authorize, audit, retain, and expire messages while
+message bodies and attachments remain client-encrypted.
+
+## Goals
+
+- asynchronous encrypted delivery for internal and portal-facing postboxes
+- personal, organizational, role-bound, and function-bound postboxes
+- attachments encrypted with the message
+- access based on current role/function membership when configured
+- honest retraction and expiry semantics
+- auditable key access, delivery, and fetch events
+- support for external recipients without platform accounts
+- replaceable identity and trust providers
+
+## Envelope Model
+
+The target model is envelope encryption:
+
+- Generate one random data encryption key per message or attachment set.
+- Encrypt content with an authenticated encryption algorithm.
+- Wrap the data encryption key for each authorized recipient or role mailbox.
+- Store only ciphertext, wrapped keys, signed manifests, and governed metadata
+  on the server.
+
+Algorithm choices should remain replaceable behind a crypto profile. The first
+profile should prefer standard, reviewed primitives such as HPKE for key
+wrapping and AEAD encryption for content.
+
+## Identity And Device Keys
+
+The platform should distinguish:
+
+- account identity
+- tenant membership
+- role/function assignment
+- device key
+- postbox binding
+
+Identity providers and directories can authenticate users and provide membership
+facts, but they must not see postbox private keys or message plaintext.
+
+The trust layer should provide:
+
+- public key directory
+- account or identity signing keys
+- per-device encryption keys
+- device registration and revocation
+- key rotation and epoch tracking
+- recovery policy hooks
+
+## Role And Function Postboxes
+
+Role-bound access needs special handling. A postbox can be bound to an
+organizational unit and a role or function. Current members can access current
+messages according to policy; former members should lose access to not-yet
+fetched material when revocation is still technically enforceable.
+
+The target design should support role encryption keys or an equivalent
+rewrapping service:
+
+- sender encrypts the content key for the role/function postbox
+- access service verifies current membership and required assurance
+- trust service rewraps the content key to the actor's current device key
+- audit records the key access decision and fetch event
+
+Key epochs are required when role membership changes. Older messages may remain
+readable according to policy, but new access must use the current epoch.
+
+## External Recipients
+
+External recipients may need one-time or time-limited access without a full
+platform account. The target model should support capability links or invitation
+tokens that are:
+
+- scoped to specific message or attachment resources
+- time-limited
+- optionally one-time
+- protected by an out-of-band secret, passphrase, or stronger external identity
+  proof
+- revocable before key fetch
+- fully audited
+
+## Retraction Semantics
+
+GovOPlaN should be honest about retraction.
+
+Before a recipient fetches a key or decrypts content, the system can revoke
+tokens, remove wrapped-key access, expire links, and delete ciphertext according
+to retention policy.
+
+After a recipient has decrypted or copied plaintext, the system cannot make the
+recipient forget it. The platform can only record access, revoke future access,
+notify parties, and apply legal or organizational controls.
+
+The UI must explain this distinction whenever it offers expiry, retraction, or
+message withdrawal.
+
+## Server Responsibilities
+
+The server remains important even when content is encrypted:
+
+- store ciphertext and signed manifests
+- store routing and policy metadata
+- enforce access before key release or rewrapping
+- provide public key directory access
+- emit notifications without plaintext content
+- record audit events
+- enforce retention and expiry where possible
+- expose diagnostics for delivery and key-access failures
+
+## Module Ownership
+
+- `govoplan-postbox` owns postbox bindings, postbox messages, message metadata,
+  and postbox UI.
+- `govoplan-identity-trust` owns device keys, public key directory, key epochs,
+  and assurance integration.
+- `govoplan-access` owns current identity, membership, function, delegation, and
+  permission decisions.
+- `govoplan-policy` owns retention, retraction, and security policy decisions.
+- `govoplan-audit` owns durable audit traces.
+- `govoplan-files` owns managed file storage when encrypted postbox attachments
+  are backed by file objects.
+
+No module should import another module's internals to decrypt content. All
+interaction must use capabilities, DTOs, and audited service contracts.

docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md

@@ -0,0 +1,276 @@
+# Public-Sector Integration Strategy
+
+GovOPlaN should integrate with the existing public-sector software landscape
+before deciding to replace specialist workflows. This document is the core
+strategy index. The executable connector catalogue lives in
+`govoplan-connectors/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md`.
+
+## Strategy Labels
+
+Use one or more of these labels for every external system family:
+
+- `integrate`: GovOPlaN talks to the system through a stable API/protocol.
+- `link`: GovOPlaN stores external references and opens the external system for
+  source-of-truth work.
+- `import`: GovOPlaN consumes data or files into governed module storage.
+- `synchronize`: GovOPlaN keeps selected records aligned both ways or through a
+  source-of-truth rule.
+- `replace selected workflow`: GovOPlaN may own a narrow workflow where the
+  external product is weak, but does not replace the whole product family.
+- `no first-class support`: GovOPlaN only stores manual references unless a
+  deployment project creates a specific connector.
+
+## Initial Classification
+
+| System family | Examples | Default strategy | Likely owner |
+| --- | --- | --- | --- |
+| File providers | SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3 | integrate, import, link | `govoplan-files`, connector inventory in `govoplan-connectors` |
+| Project/task management | OpenProject, Jira, Redmine, Microsoft Planner | link, synchronize selected records, replace selected workflow only after proof | `govoplan-connectors`, later `govoplan-tasks` or workflow modules |
+| Identity providers | LDAP, Active Directory, OIDC, SAML, OpenDesk IDM | integrate, synchronize | `govoplan-idm`, `govoplan-access` |
+| Mail and groupware | IMAP/SMTP, Open-Xchange, Exchange/M365, CalDAV/CardDAV | integrate, link | `govoplan-mail`, `govoplan-calendar`, `govoplan-connectors` |
+| DMS/e-file/archive | d.velop/d.3, enaio, ELO, Fabasoft, CMIS, VIS/eAkte | link, import, synchronize selected metadata | `govoplan-dms`, `govoplan-files`, `govoplan-records` |
+| ERP/finance/procurement | SAP, MACH, Infoma, DATEV, procurement feeds | export, import, synchronize; do not replace by default | `govoplan-erp`, `govoplan-procurement`, `govoplan-ledger`, `govoplan-payments` |
+| Public-sector transport | FIT-Connect, XTA/OSCI, Peppol access points | integrate, publish, receive | dedicated protocol modules plus `govoplan-connectors` inventory |
+| Standards registries | XRepository, XOE/V catalogues | link, import metadata/cache | `govoplan-connectors`, `govoplan-xoev` |
+| Publication/data exchange | RSS, open-data APIs, API feeds, CSV/Excel drops | consume, publish, transform | proposed `govoplan-datasources`, proposed `govoplan-dataflow`, `govoplan-reporting` |
+| Collaboration suites | Matrix, Jitsi, BigBlueButton, Nextcloud Talk, Collabora/OnlyOffice | integrate, link; native behavior only for governed evidence | `govoplan-connectors`, `govoplan-dms`, `govoplan-workflow` |
+| Specialist Fachverfahren | register-specific and domain-specific systems | link first; integrate/import when a real project supplies contracts | domain module or deployment-specific connector |
+
+## Landscape Catalogue
+
+This catalogue is intentionally implementation-oriented. Each entry records the
+first API/auth/data assumptions needed to turn an inventory entry into a
+connector or module issue.
+
+### Citizen And Service Portals
+
+- Strategy: integrate/link first; replace selected intake workflow only when a
+  GovOPlaN portal package owns the complete journey.
+- Protocol/API surface: REST/JSON APIs, form submission webhooks, OIDC/SAML
+  login, eID interfaces where available, file-upload callbacks, case-status
+  callbacks.
+- Auth model: OIDC/SAML service clients, signed webhook secrets, tenant-scoped
+  API keys, later eID/trust-provider handoff.
+- Data shape: applicant identity reference, application form payload,
+  attachment references, consent declarations, status events, receipt IDs.
+- Deployment assumptions: externally reachable HTTPS, reverse proxy, portal DMZ
+  separation, strict CSRF/origin settings, large upload path.
+- Risks: personal data exposure, duplicate identity mapping, partial
+  submissions, upload malware, inconsistent portal status models.
+- MVP test path: submit a test application with one file, create a form
+  submission/case/task stub, return a receipt and status reference.
+- Owner/priority: `govoplan-portal`, `govoplan-forms-runtime`,
+  `govoplan-files`, Wave 1.
+
+### DMS, E-File, Records, And Archives
+
+- Strategy: link/import/synchronize selected metadata; do not replace the DMS by
+  default.
+- Protocol/API surface: CMIS, WebDAV, vendor REST APIs, S3/object archive
+  staging, file-plan export/import, archive handoff APIs.
+- Auth model: service accounts, OAuth/OIDC where supported, mTLS for regulated
+  archives, secret references for vendor tokens.
+- Data shape: document ID, version, file-plan/classification code, retention
+  metadata, owner/case reference, external URL, checksum, lock/legal-hold state.
+- Deployment assumptions: usually internal network or VPN, strict storage
+  quotas, existing retention policies, archive immutability requirements.
+- Risks: record duplication, broken legal hold, permission mismatch, version
+  drift, destructive retention/export mistakes.
+- MVP test path: create a connector inventory entry, test read-only metadata
+  lookup, link one GovOPlaN file/case evidence item to an external document.
+- Owner/priority: `govoplan-dms`, `govoplan-records`, `govoplan-files`,
+  `govoplan-connectors`, Wave 2/5.
+
+### ERP, Finance, Procurement, And Accounting
+
+- Strategy: export/import/synchronize selected records; replacement only by
+  narrow domain decision.
+- Protocol/API surface: vendor REST/SOAP APIs, CSV/XML batch exchange, SFTP,
+  XRechnung/Peppol, XBestellung/procurement feeds, payment reconciliation files.
+- Auth model: service accounts, client certificates, mTLS, SFTP keys, token
+  references, environment-specific account separation.
+- Data shape: debtor/creditor reference, payment request, invoice, order,
+  budget/cost-center code, booking status, receipt/evidence reference.
+- Deployment assumptions: batch windows, finance-system approval workflows,
+  test tenants often separated from production by vendor process.
+- Risks: financial posting errors, double export, tax/legal data retention,
+  inconsistent master data, irreversible accounting handoff.
+- MVP test path: dry-run export of one payment/accounting handoff file with
+  checksum, validation report, and no remote posting.
+- Owner/priority: `govoplan-payments`, `govoplan-ledger`,
+  `govoplan-xrechnung`, `govoplan-erp`, `govoplan-procurement`, Wave 1/6.
+
+### Identity, IAM, And Directory Services
+
+- Strategy: integrate/synchronize; access remains GovOPlaN's local
+  authorization boundary.
+- Protocol/API surface: LDAP, Active Directory, SCIM, OIDC, SAML, OpenDesk IDM
+  APIs, group membership sync, account deactivation feeds.
+- Auth model: bind accounts, service clients, OIDC/SAML metadata, SCIM tokens,
+  certificate-backed clients where required.
+- Data shape: account, user, group, membership, role claim, tenant/org-unit
+  mapping, status, external directory ID.
+- Deployment assumptions: directory is usually internal; identity provider may
+  be organization-wide and not GovOPlaN-owned.
+- Risks: privilege escalation through group mapping, stale memberships, account
+  collision, deprovisioning latency, tenant-boundary mistakes.
+- MVP test path: read-only directory profile test, map one external group to a
+  tenant group, show a dry-run membership diff.
+- Owner/priority: `govoplan-idm`, `govoplan-access`, Wave 1.
+
+### Groupware, Mail, Calendar, And Collaboration
+
+- Strategy: integrate/link; native behavior only where GovOPlaN needs governed
+  evidence or process state.
+- Protocol/API surface: IMAP/SMTP, CalDAV/CardDAV, Open-Xchange APIs, Microsoft
+  Graph/EWS, Matrix APIs, Jitsi/BigBlueButton APIs, Collabora/OnlyOffice
+  integration points.
+- Auth model: service accounts, delegated OAuth/OIDC, app passwords, mailbox
+  credentials, groupware-specific tokens, secret references.
+- Data shape: mailbox folder/message references, event/free-busy data, meeting
+  URL, chat room ID, participant list, document-editing session reference.
+- Deployment assumptions: often internal/existing tenant infrastructure; mail
+  and calendar may be separate from identity even in OpenDesk-style stacks.
+- Risks: mail credential exposure, calendar privacy, double invitations, room
+  booking conflicts, chat/document data escaping retention rules.
+- MVP test path: profile test for mailbox/calendar reachability, read-only
+  folder/free-busy lookup, create a non-production event/message draft.
+- Owner/priority: `govoplan-mail`, `govoplan-calendar`,
+  `govoplan-connectors`, Wave 1/2.
+
+### Payment And Public Cashier Systems
+
+- Strategy: integrate/export/import; keep the payment provider or cashier as
+  source of settlement truth.
+- Protocol/API surface: payment provider APIs, redirect/callback flows,
+  reconciliation files, SEPA/export formats, cash-register/cashier interfaces.
+- Auth model: provider API keys, signed webhooks, client certificates, mTLS,
+  tenant-specific merchant accounts.
+- Data shape: payment intent, amount/currency, payer reference, provider
+  transaction ID, settlement status, receipt, refund/cancellation reference.
+- Deployment assumptions: public callback URLs, strict environment separation,
+  PCI-sensitive providers, finance reconciliation cadence.
+- Risks: duplicate charges, callback replay, amount mismatch, refund workflow
+  gaps, evidence-retention mistakes.
+- MVP test path: sandbox payment intent, signed callback verification, receipt
+  evidence link, reconciliation dry-run.
+- Owner/priority: `govoplan-payments`, `govoplan-ledger`, Wave 1/6.
+
+### Reporting, BI, Open Data, And Publication
+
+- Strategy: consume/publish/transform; native reporting owns GovOPlaN views, not
+  every external BI product.
+- Protocol/API surface: SQL read replicas, CSV/Excel export/import, REST APIs,
+  RSS/Atom, open-data APIs, SFTP/WebDAV publication targets.
+- Auth model: read-only DB users, API tokens, SFTP keys, OAuth clients, public
+  anonymous publication profiles where appropriate.
+- Data shape: dataset metadata, schema/version, report parameters, generated
+  file references, publication URL, freshness/lineage, validation results.
+- Deployment assumptions: publication can be public or internal; generated
+  datasets need retention and provenance.
+- Risks: leaking restricted data, stale publications, schema drift, expensive
+  queries, untraceable manual transformations.
+- MVP test path: publish one report/export as a governed file plus RSS/Atom
+  entry with checksum, timestamp, and permission check.
+- Owner/priority: `govoplan-reporting`, `govoplan-connectors`, possible future
+  `govoplan-datasources`/`govoplan-dataflow`, Wave 2.
+
+### Public-Sector Protocols And Registries
+
+- Strategy: integrate/publish/receive; protocol modules own protocol semantics.
+- Protocol/API surface: FIT-Connect, XTA/OSCI, XRepository, XOE/V, XRechnung,
+  XBestellung, Peppol, registry-specific Fachverfahren APIs.
+- Auth model: certificates, mTLS, service accounts, destination credentials,
+  protocol-specific trust anchors and key rotation.
+- Data shape: transport envelope, payload schema/version, destination IDs,
+  receipt/acknowledgement, message status, standard-specific metadata.
+- Deployment assumptions: regulated trust chains, test/prod endpoint
+  separation, formal onboarding, strict logging and retention expectations.
+- Risks: invalid schemas, failed delivery receipts, certificate expiry, wrong
+  destination routing, protocol version drift.
+- MVP test path: validate a sample payload against a schema, test endpoint
+  reachability in sandbox, store receipt/evidence reference.
+- Owner/priority: `govoplan-fit-connect`, `govoplan-xoev`,
+  `govoplan-xrechnung`, `govoplan-xta-osci`, `govoplan-connectors`, Wave 1/2.
+
+### File Providers And Shared Storage
+
+- Strategy: integrate/import/link; files module owns GovOPlaN file semantics.
+- Protocol/API surface: SMB/CIFS, WebDAV, Nextcloud, Seafile, SFTP, S3,
+  local/object storage profiles.
+- Auth model: service accounts, user credentials, app tokens, OAuth where
+  supported, secret references, environment variables for deployment-managed
+  credentials.
+- Data shape: file ID/path, provider object ID, checksum, MIME type, size,
+  version/ETag, owner, permission snapshot, imported file reference.
+- Deployment assumptions: internal networks, large files, existing shares,
+  variable permissions, provider-specific rate limits.
+- Risks: permission mismatch, stale imports, overwrites, duplicate files, path
+  traversal, storage growth.
+- MVP test path: profile test, list folder, import one file into governed
+  storage, keep provider reference and checksum.
+- Owner/priority: `govoplan-files`, `govoplan-connectors`, Wave 0/1.
+
+### Project, Task, And Case-Adjacent Systems
+
+- Strategy: connector-first for OpenProject/Jira/Redmine; native module only
+  when GovOPlaN owns project semantics.
+- Protocol/API surface: OpenProject API v3, webhooks, Jira/Redmine REST APIs,
+  Microsoft Graph for Planner/Project where applicable.
+- Auth model: API tokens, OAuth/OIDC apps, webhook secrets, service accounts.
+- Data shape: project ID, work package/task ID, status, assignee reference,
+  external URL, version/lock token, publish/sync trace.
+- Deployment assumptions: external project tool remains source of truth for
+  broad project management; GovOPlaN links selected records.
+- Risks: task duplication, bidirectional sync conflicts, permission mismatch,
+  over-mirroring comments/attachments.
+- MVP test path: OpenProject profile test, project/work-package lookup,
+  external-reference round-trip.
+- Owner/priority: `govoplan-connectors`, later `govoplan-tasks`/workflow/cases
+  consumers, Wave 0/2.
+
+### Specialist Fachverfahren
+
+- Strategy: link first; integrate/import only when a deployment project supplies
+  concrete contracts and a domain owner.
+- Protocol/API surface: vendor APIs, CSV/XML batch imports, SFTP, database
+  views, message queues, protocol-specific transports.
+- Auth model: usually service accounts, VPN, mTLS, SFTP keys, or vendor tokens.
+- Data shape: domain-specific record IDs, status, applicant/person references,
+  file/evidence references, case/status events.
+- Deployment assumptions: strongly local/vendor-specific, often no stable test
+  API, data model differs by jurisdiction.
+- Risks: brittle vendor contracts, legal source-of-truth ambiguity, high
+  customization cost, migration expectations.
+- MVP test path: inventory entry and manual external-reference link; require a
+  project-specific connector issue before automation.
+- Owner/priority: domain module or deployment-specific connector, case by case.
+
+## Prioritization Rules
+
+1. Start with connectors that unblock Wave 0 or Wave 1 reference journeys.
+2. Prefer open standards and self-hosted/open-source APIs where they are common
+   in public-sector deployments.
+3. Treat inventory-only entries as useful because operators need a map of their
+   software landscape even before automation exists.
+4. Keep connector code in the owning connector/protocol module. Domain modules
+   consume capabilities, DTOs, external references, and events through core.
+5. Every executable connector needs health diagnostics, secret-reference
+   handling, lifecycle state, audit events, and retirement behavior.
+
+## Connector Catalogue Handoff
+
+`govoplan-connectors` owns the detailed catalogue entry shape:
+
+- connector type key
+- category and owner module
+- supported directions and trigger modes
+- credential and secret handling
+- health check and diagnostics payload
+- external-reference shape
+- required capabilities and optional module combinations
+- lifecycle support
+
+Core should only keep strategy, routing, and cross-module architecture notes.
+Connector implementation and public-sector target inventory belong in
+`govoplan-connectors`.

docs/RBAC_MANIFEST.md

@@ -1,291 +0,0 @@
-# Multi Seal Mail - Current RBAC and Resource-Access Model
-
-**Updated:** 2026-06-16
-**Current migration head:** `f5a6b7c8d9e0`
-
-## Authorization Equation
-
-An operation is permitted only when every applicable layer allows it:
-
-```text
-effective role/API-key capability
-AND resource ownership/share access
-AND workflow state
-AND active governance/policy constraints
-```
-
-RBAC answers what an actor may do. ACLs answer which resource the actor may do it to. Workflow state and policy decide whether the operation is currently valid.
-
-## Identity and Scope
-
-```text
-Account                         global login identity
-+- User membership               tenant-local identity
-   +- direct tenant roles
-   +- active group memberships
-   |  +- inherited tenant roles
-   +- tenant-local API keys
-
-Account
-+- direct system-role assignments
-```
-
-A browser session has one active tenant membership. System privileges do not silently grant tenant data access. API keys remain tenant-local and receive the intersection of their configured scopes and their owner's live tenant scopes on every request.
-
-## Wildcards
-
-```text
-tenant:*   every canonical tenant permission
-system:*   every canonical system permission
-*          legacy alias interpreted as tenant:* only
-```
-
-Tenant wildcards never grant system permissions.
-
-## Canonical Tenant Permissions - 53
-
-### Campaigns
-
-```text
-campaign:read
-campaign:create
-campaign:update
-campaign:copy
-campaign:archive
-campaign:delete
-campaign:share
-campaign:validate
-campaign:build
-campaign:review
-campaign:send_test
-campaign:queue
-campaign:control
-campaign:send
-campaign:retry
-campaign:reconcile
-```
-
-### Recipients
-
-```text
-recipients:read
-recipients:write
-recipients:import
-recipients:export
-```
-
-### Files
-
-```text
-files:read
-files:download
-files:upload
-files:organize
-files:share
-files:delete
-files:admin
-```
-
-### Reports and Audit
-
-```text
-reports:read
-reports:export
-reports:send
-audit:read
-```
-
-### Mail Servers
-
-```text
-mail_servers:read
-mail_servers:use
-mail_servers:test
-mail_servers:write
-mail_servers:manage_credentials
-```
-
-### Tenant Administration
-
-```text
-admin:users:read
-admin:users:create
-admin:users:update
-admin:users:suspend
-
-admin:groups:read
-admin:groups:write
-admin:groups:manage_members
-
-admin:roles:read
-admin:roles:write
-admin:roles:assign
-
-admin:api_keys:read
-admin:api_keys:create
-admin:api_keys:revoke
-
-admin:settings:read
-admin:settings:write
-admin:policies:read
-admin:policies:write
-```
-
-## Canonical System Permissions - 18
-
-```text
-system:tenants:read
-system:tenants:create
-system:tenants:update
-system:tenants:suspend
-
-system:accounts:read
-system:accounts:create
-system:accounts:update
-system:accounts:suspend
-
-system:roles:read
-system:roles:write
-system:roles:assign
-
-system:access:read
-system:access:assign
-
-system:audit:read
-system:settings:read
-system:settings:write
-system:governance:read
-system:governance:write
-```
-
-`system:access:*` remains as a compatibility/read and assignment boundary for cross-tenant/system access handling. It is not a separate primary UI area.
-
-## Default Tenant Roles
-
-- **Owner:** `tenant:*`. At least one active operational owner must remain.
-- **Tenant administrator:** settings, policies, users, groups, roles and API keys plus read access to campaigns/files/reports/audit. Real delivery remains separately delegable.
-- **Administrator (legacy):** all tenant permissions for upgraded installations.
-- **Access administrator:** membership and assignment management within delegation limits.
-- **Campaign manager:** prepare, validate and build campaigns; no review approval or real delivery by default.
-- **Reviewer:** inspect and approve prepared campaign messages.
-- **Sender:** mock-test, queue, control, send, retry and reconcile prepared campaigns; can use/test approved mail profiles.
-- **File manager:** managed file operations without campaign delivery rights.
-- **Viewer:** read campaigns, recipients, files and reports.
-- **Auditor:** read campaigns, recipient evidence, reports and audit records; export detailed evidence.
-
-## Default System Roles
-
-- **System owner:** `system:*`, protected. At least one active account must retain it.
-- **System administrator:** all specific system permissions, editable and not protected.
-- **System auditor:** read-only system registry/settings/governance/audit role, editable.
-
-## Delegation Ceiling
-
-For role definition, assignment and API-key creation:
-
-```text
-requested scopes subset of actor delegateable scopes
-```
-
-Rules:
-
-1. Tenant roles may contain tenant scopes only.
-2. System roles may contain system scopes only.
-3. Definition rights and assignment rights are separate.
-4. Group definition and group membership management are separate.
-5. API-key scopes are intersected with the owner's current effective scopes on every request.
-6. Suspended accounts, users, tenants or groups stop contributing access immediately.
-7. Administrative updates are field-sensitive; a user with only status authority cannot change role assignments.
-
-## Campaign Ownership and ACLs
-
-A campaign has exactly one owner:
-
-```text
-owner user OR owner group
-```
-
-Additional active shares may target users or groups with `read` or `write`.
-
-Resolution:
-
-- owner user: read and write;
-- member of owner group: read and write;
-- explicit read share: read;
-- explicit write share: read and write;
-- `tenant:*`: tenant-wide ACL bypass;
-- ordinary campaign permission without ownership/share: no object access.
-
-ACLs do not add capabilities. A write share still needs the specific permission for update, validation, review, send, report, retry or reconciliation.
-
-## Sensitive Recipient Boundary
-
-Recipient-complete campaign JSON, message data and job detail require `recipients:read`. Recipient edits require `recipients:write`; exports require `recipients:export`; import is reserved for the dedicated recipient import/list workflow.
-
-## Files
-
-| Permission | Operations |
-|---|---|
-| `files:read` | list, search, inspect, resolve metadata |
-| `files:download` | download file bytes and generated ZIP archives |
-| `files:upload` | upload files and ZIP contents |
-| `files:organize` | create folders, rename, move, copy and bulk rename |
-| `files:share` | create/revoke file shares |
-| `files:delete` | delete/hide files and folders subject to retention |
-| `files:admin` | tenant-wide administration of user/group file spaces |
-
-## Mail Servers
-
-| Permission | Boundary |
-|---|---|
-| `mail_servers:read` | profile metadata and effective policy visibility |
-| `mail_servers:use` | select an approved profile without reading secrets |
-| `mail_servers:test` | run server-side connection tests |
-| `mail_servers:write` | define/edit profiles in allowed scopes |
-| `mail_servers:manage_credentials` | create/replace SMTP/IMAP secrets or campaign-level credentials where policy allows |
-
-Reusable encrypted profiles now exist. Effective usability is also constrained by hierarchical mail-profile policy, ownership, allowed/forced profile sets, credential inheritance/override rules and allow/deny patterns.
-
-## Sessions, API Keys and CSRF
-
-- Browser login creates an HttpOnly session cookie and a separate readable CSRF cookie.
-- Unsafe cookie-authenticated requests require matching CSRF cookie/header and stored CSRF hash.
-- API keys remain supported for CLI/automation and do not use browser CSRF.
-- Login responses still expose a compatibility session token in the response body; the WebUI does not persist it.
-
-## Legacy Compatibility
-
-Runtime aliases remain only for names that are no longer canonical, including:
-
-```text
-campaign:write
-attachments:read
-attachments:write
-admin:users
-admin:users:write
-admin:api_keys:write
-admin:settings
-system:tenants:write
-system:access:write
-```
-
-Canonical scopes are not widened by runtime alias expansion after migration.
-
-## Deferred Permission Families
-
-Add these only with their corresponding implemented features:
-
-```text
-templates:*
-address_books:*
-recipient_lists:*
-connectors:*
-dsar:*
-system:monitoring:read
-system:backups:run
-system:backups:restore
-system:updates:apply
-system:updates:rollback
-```
-
-A separate `retention:*` family is not currently canonical because retention is managed through system settings and tenant policy scopes. Add it only if retention operation duties need separation from general policy/settings administration.

docs/RELEASE_DEPENDENCIES.md

@@ -1,50 +1,903 @@
 # GovOPlaN Release Dependencies
 
-Release installs must not depend on sibling checkout paths. Local development can keep editable installs and `file:` WebUI links, but release packaging should resolve modules from tagged git refs or from a package registry.
+This document owns release package composition, signed package catalogs,
+license checks, catalog publishing, migration baselines, and the final release
+checklist.
 
-## Backend
+Operator runtime configuration and module install/uninstall execution live in
+`DEPLOYMENT_OPERATOR_GUIDE.md`.
+
+## Backend Packages
+
+Release installs must not depend on sibling checkout paths. Local development
+can keep editable installs and `file:` WebUI links, but release packaging must
+resolve modules from tagged git refs or from a package registry.
 
 Local development:
 
 ```bash
-cd /mnt/DATA/git/govoplan-core
+cd /mnt/DATA/git/govoplan
 ./.venv/bin/python -m pip install -r requirements-dev.txt
 ```
 
-Release install from tagged module repositories:
+Release install from the meta checkout plus tagged module repositories:
 
 ```bash
-cd /mnt/DATA/git/govoplan-core
+cd /mnt/DATA/git/govoplan
 ./.venv/bin/python -m pip install -r requirements-release.txt
 ```
 
-`requirements-release.txt` pins the module repositories to the release tag. Update those refs when cutting a release:
-
-```text
-govoplan-files    git@git.add-ideas.de:add-ideas/govoplan-files.git    v0.1.0
-govoplan-mail     git@git.add-ideas.de:add-ideas/govoplan-mail.git     v0.1.0
-govoplan-campaign git@git.add-ideas.de:add-ideas/govoplan-campaign.git v0.1.0
-```
-
-## WebUI
-
-Local development uses `webui/package.json`, which may point at sibling module checkouts while active development is happening.
-
-Release WebUI installs should use `webui/package.release.json`. It points module dependencies at the same tagged git repositories. To generate a release lockfile, copy it over `package.json` in a release branch or build workspace and then run `npm install` there:
+`../govoplan-core[server]` is resolved relative to the meta requirements file.
+If you create the virtualenv elsewhere, still run the install command from the
+meta checkout:
 
 ```bash
+cd /mnt/DATA/git/govoplan
+/tmp/govoplan-release-test/bin/python -m pip install -r requirements-release.txt
+```
+
+`requirements-release.txt` pins the module repositories to the release tag.
+Update those refs when cutting a release:
+
+```text
+govoplan-access   git@git.add-ideas.de:add-ideas/govoplan-access.git   v0.1.6
+govoplan-admin    git@git.add-ideas.de:add-ideas/govoplan-admin.git    v0.1.6
+govoplan-tenancy  git@git.add-ideas.de:add-ideas/govoplan-tenancy.git  v0.1.6
+govoplan-organizations git@git.add-ideas.de:add-ideas/govoplan-organizations.git v0.1.6
+govoplan-identity git@git.add-ideas.de:add-ideas/govoplan-identity.git v0.1.6
+govoplan-policy   git@git.add-ideas.de:add-ideas/govoplan-policy.git   v0.1.6
+govoplan-audit    git@git.add-ideas.de:add-ideas/govoplan-audit.git    v0.1.6
+govoplan-files    git@git.add-ideas.de:add-ideas/govoplan-files.git    v0.1.6
+govoplan-mail     git@git.add-ideas.de:add-ideas/govoplan-mail.git     v0.1.6
+govoplan-campaign git@git.add-ideas.de:add-ideas/govoplan-campaign.git v0.1.6
+govoplan-calendar git@git.add-ideas.de:add-ideas/govoplan-calendar.git v0.1.6
+```
+
+## WebUI Packages
+
+Local development uses `webui/package.json`, which may point at sibling module
+checkouts while active development is happening.
+
+Release WebUI installs should use `webui/package.release.json`. It points
+module dependencies at the same tagged git repositories. After the module tags
+referenced there exist, generate the committed release lockfile without
+touching the development package files:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/release/generate-release-lock.sh
 cd /mnt/DATA/git/govoplan-core/webui
-cp package.release.json package.json
-PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm install
 PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run build
 ```
 
-The module repositories include root-level npm package manifests so git installs can resolve `@govoplan/files-webui`, `@govoplan/mail-webui`, and `@govoplan/campaign-webui` from repository roots even though their source lives below `webui/src`.
+The module repositories include root-level npm package manifests so git
+installs can resolve `@govoplan/access-webui`, `@govoplan/admin-webui`,
+`@govoplan/files-webui`, `@govoplan/mail-webui`,
+`@govoplan/campaign-webui`, and `@govoplan/calendar-webui` from repository
+roots even though their source lives below `webui/src`.
+
+### Release Lockfile Strategy
+
+The supported release composition currently is the full GovOPlaN product: core
+plus access, admin, tenancy, organizations, identity, policy, audit,
+dashboard, files, mail, campaign, calendar, docs, and ops. Keep one committed
+full-product release lockfile at
+`webui/package-lock.release.json`, generated from
+`webui/package.release.json` in a clean release workspace. Development
+`package-lock.json` may continue to point at local `file:` dependencies.
+
+Frontend module permutations are regression-tested through
+`GOVOPLAN_WEBUI_MODULE_PACKAGES` and temporary build output, not through
+committed lockfiles for every possible combination. If a smaller composition
+becomes a separately shipped product, add an explicit release manifest and
+lockfile pair for that product, for example
+`package.release.files-mail.json` and `package-lock.release.files-mail.json`,
+generated in a clean release workspace from tagged git dependencies.
+
+## Release Tag Script
+
+The normal release path is automated by `/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh`: it bumps
+or accepts the target version, updates Python/WebUI/module manifest versions,
+commits/tags/pushes the module repositories first, regenerates
+`webui/package-lock.release.json`, and then commits/tags/pushes core. If the
+working tree has already been bumped, pass the current version explicitly:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/release/push-release-tag.sh --version 0.1.6
+```
+
+`/mnt/DATA/git/govoplan/tools/release/generate-release-catalog.py` reads installed/discovered
+`ModuleManifest` objects while writing catalog entries. When a manifest is
+available, the catalog entry uses the manifest version, points package refs at
+`v<manifest.version>`, and copies `provides_interfaces` /
+`requires_interfaces` from the manifest. It also copies module migration order
+and `migration_tasks` metadata when present. If a manifest cannot be
+discovered, the entry falls back to the release version passed with `--version`
+and omits interface and migration-task metadata. This keeps the catalog aligned
+with independently versioned module packages instead of relying on a hardcoded
+compatibility table.
+
+The script also includes GovOPlaN roadmap/scaffold module repositories that do
+not yet have package metadata. Those repositories are committed, tagged, and
+pushed with the same release tag, but they are tag-only until they contain
+`pyproject.toml`, module manifests, or WebUI packages. Tag-only repositories
+are not listed in `requirements-release.txt` or `webui/package.release.json`.
+
+Current tag-only module repositories:
+
+- `govoplan-addresses`
+- `govoplan-appointments`
+- `govoplan-cases`
+- `govoplan-connectors`
+- `govoplan-dms`
+- `govoplan-erp`
+- `govoplan-fit-connect`
+- `govoplan-forms`
+- `govoplan-identity-trust`
+- `govoplan-idm`
+- `govoplan-ledger`
+- `govoplan-notifications`
+- `govoplan-payments`
+- `govoplan-portal`
+- `govoplan-reporting`
+- `govoplan-scheduling`
+- `govoplan-search`
+- `govoplan-tasks`
+- `govoplan-templates`
+- `govoplan-workflow`
+- `govoplan-xoev`
+- `govoplan-xrechnung`
+- `govoplan-xta-osci`
+
+## Catalog Trust And Licensing
+
+GovOPlaN module install and uninstall must remain operator-controlled. The
+running server may plan and validate package changes, but package mutation is
+performed by the separate installer daemon or an operator shell during
+maintenance mode.
+
+`addideas-govoplan-website` is the public static distribution surface for
+official catalog resources:
+
+- signed module package catalogs, grouped by release channel
+- public catalog keyrings
+- public license verification keyrings
+- examples and operator-facing download paths
+
+`govoplan-core` is the verifier and orchestrator:
+
+- fetches a local or remote module catalog
+- verifies catalog signatures against configured trusted keys
+- enforces approved release channels
+- rejects expired or not-yet-valid catalogs
+- records accepted catalog sequence numbers for replay protection
+- checks catalog entry license feature requirements before planning installs
+- writes installer plans and request records
+
+Feature and platform modules own their package artifacts, manifests, migration
+metadata, retirement providers, and optional lifecycle behavior.
+
+Core accepts either a local catalog file or a remote URL:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG=/srv/govoplan/catalogs/stable.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_URL=https://govoplan.example/catalogs/v1/channels/stable.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_CACHE=/srv/govoplan/runtime/catalog-cache/stable.json
+```
+
+If both file and URL are set, the URL wins. The cache is used when a remote
+fetch fails, so an operator can still inspect the last known catalog. A cached
+catalog must still pass signature, freshness, channel, and replay validation.
+
+An official catalog is a JSON object with:
+
+- `catalog_version`
+- `channel`
+- `sequence`
+- `generated_at`
+- `not_before` when delayed activation is needed
+- `expires_at`
+- `modules`
+- `signatures`
+
+Each module entry can declare:
+
+- backend package name and pinned install reference
+- WebUI package name and pinned install reference
+- display metadata and tags
+- `license_features`, the feature entitlements required to plan that install
+- `dependencies` and `optional_dependencies`, the module ids expected in the
+  target module set
+- `migration_safety`, one of `automatic`, `requires_review`, `forward_only`,
+  or `destructive`
+- `migration_notes`, operator-facing data/migration guidance for review,
+  forward-only, or destructive changes
+- `migration_after` and `migration_before`, explicit module ids used to order
+  module-owned migration heads when a release needs a live-data sequencing rule
+- `migration_tasks`, constrained live-data tasks that run around Alembic
+  migration phases. Each task declares `task_id`, `phase`, `summary`,
+  `task_version`, `safety`, `idempotent`, and optionally `timeout_seconds`.
+  The allowed phases are `pre_migration_check`, `pre_migration_prepare`,
+  `post_migration_backfill`, and `post_migration_verify`.
+- `current_version_min` and `current_version_max_exclusive`, the installed
+  version window from which this catalog target may be applied directly
+- `bridge_release` and `bridge_notes`, marking a target as an intermediate
+  compatibility release in a staged update path
+- `allow_downgrade` and `allow_same_version`, explicit opt-ins for reviewed
+  rollback or package-refresh plans
+- `recovery_tested` and `recovery_notes`, documenting the rehearsal for
+  forward-only or destructive data changes
+- `provides_interfaces`, named interface contracts exported by this module
+- `requires_interfaces`, named interface contracts and version ranges required
+  by this module
+
+The signature is Ed25519 over canonical JSON with both `signature` and
+`signatures` removed. Core accepts the legacy single `signature` field and the
+new `signatures` array.
+When `APP_ENV` is `prod` or `production`, module package catalog signature
+verification is required by default unless
+`GOVOPLAN_MODULE_PACKAGE_CATALOG_REQUIRE_SIGNATURE=false` is set explicitly.
+
+### Independent Module Versions And Interface Ranges
+
+Modules do not need to ship on the same version number. Release catalogs should
+pin each package to the exact backend/WebUI ref being installed and declare any
+cross-module API compatibility through named interfaces.
+
+Provider shape:
+
+```json
+"provides_interfaces": [
+  { "name": "files.campaign_attachments", "version": "1.4.0" }
+]
+```
+
+Requirement shape:
+
+```json
+"requires_interfaces": [
+  {
+    "name": "files.campaign_attachments",
+    "version_min": "1.0.0",
+    "version_max_exclusive": "2.0.0"
+  }
+]
+```
+
+`version_min` is inclusive. `version_max_exclusive` is exclusive, so the range
+above means `>= 1.0.0` and `< 2.0.0`. Use this for SemVer major-version
+compatibility lines. Set `"optional": true` only when the module can operate
+without that interface being present. If a provider is installed but its
+version is outside the declared optional range, activation is still blocked.
+
+Catalog validation normalizes these fields and warns when catalog entries do
+not satisfy each other's ranges. Registry activation and installer preflight
+perform the blocking checks against the discovered installed manifests before
+the desired module set is activated.
+The admin module-management UI shows catalog warnings in the package catalog
+section and repeats them as warning-level installer preflight issues while a
+package install is planned.
+
+Install-plan items carry a `source` field. Manually entered items use
+`source: "manual"`; entries planned from the package catalog use
+`source: "catalog"`. Catalog-sourced items also carry a `catalog` metadata
+object with the validation snapshot used when the item was planned: catalog
+source/path, source type, cache path, channel, sequence, generated/validity
+timestamps, signature state, trusted key id, and cache state where available.
+Catalog provenance changes preflight severity:
+
+- catalog-sourced installs and updates require a configured, valid package
+  catalog before activation
+- invalid, untrusted, expired, not-yet-valid, replayed, or unapproved-channel
+  catalogs block catalog-sourced installs and updates
+- the same catalog validation failures remain warnings for manual install
+  plans, so operators can still use offline or emergency package refs
+- valid-catalog warnings, such as intentionally unsigned local catalogs when
+  signature enforcement is disabled, remain warnings
+- selected catalog entries with unsatisfied non-optional named interface ranges
+  block activation before the installer runs
+- selected catalog entries whose target dependencies are neither installed nor
+  planned block activation before the installer runs
+- catalog update targets older than the installed module version block unless
+  the catalog entry declares `allow_downgrade: true`
+- catalog update targets equal to the installed module version block unless the
+  catalog entry declares `allow_same_version: true`
+- catalog update targets with a `current_version_min` /
+  `current_version_max_exclusive` window block when the installed version is
+  outside that window; publish and apply a bridge release instead
+- catalog entries marked `forward_only` or `destructive` block activation until
+  the plan row has an explicit data-safety acknowledgement
+- catalog entries marked `forward_only` or `destructive` also block unless the
+  catalog entry declares `recovery_tested: true` and either the catalog entry or
+  operator plan row contains recovery notes
+- catalog entries marked `destructive` also require catalog migration notes or
+  operator notes describing the cleanup or retirement plan
+
+### Update Paths
+
+Package updates are target-state operations, not one-module-at-a-time runtime
+toggles. The safe unit of planning is a desired module version set plus a
+catalog validation snapshot. The installer may install multiple packages into
+the environment before activation, then validate the discovered manifests and
+activate the resulting set together.
+
+Install-plan rows support explicit `install`, `update`, and `uninstall`
+actions. Catalog planning writes `update` when the module is already installed.
+Preflight resolves the target set from installed manifests plus the planned
+catalog entries. Unplanned catalog entries are not treated as installed. When a
+catalog entry would satisfy a missing dependency or named interface, preflight
+blocks activation with a companion-update issue; the admin catalog planner adds
+those companion rows automatically when it can resolve them from the current
+catalog. The preflight response also includes a structured `target_plan` summary
+with each planned module's action, current version, catalog target version,
+package refs, migration-safety level, current-version update window, bridge
+metadata, recovery metadata, and acknowledgement state.
+
+Database migrations are planned against that same target module set. When the
+installer is run with `--migrate`, it calls `govoplan_core.commands.init_db`
+with the target enabled modules rather than the pre-update startup module list,
+so newly installed module migration directories are discovered before
+activation. Preflight also returns a structured migration plan. Its step order is
+derived from:
+
+- manifest and catalog `migration_after` / `migration_before` declarations
+- module dependencies and optional dependencies when both modules are in the
+  target plan
+- named interface provider/consumer relationships when both sides are in the
+  target plan
+
+Preflight blocks cycles in that ordering graph. It also blocks non-idempotent
+module migration tasks, forward-only/destructive tasks without operator
+acknowledgement, and installed manifest tasks that declare no executor.
+Catalog-only task executors are marked as pending because they can only be
+confirmed after the target package is installed. The migrator runs pre-migration
+tasks, upgrades the ordered module heads first, finishes with Alembic `heads`,
+and then runs post-migration tasks, so Alembic's revision graph remains
+authoritative while GovOPlaN still gives operators a module-aware live-data
+order.
+
+This avoids circular "upgrade A first / upgrade B first" traps: named interface
+requirements are solved against the target set, not against each intermediate
+package-install moment. If the target set cannot satisfy all non-optional
+interfaces and module dependencies at once, the plan is invalid. Operators
+should add the necessary module updates to the same plan instead of trying to
+force an order.
+
+Live data upgrades need an even stricter rule:
+
+- migrations must be idempotent and ordered by module migration metadata
+- destructive schema/data changes need an explicit retirement or cleanup plan,
+  not an automatic package update side effect
+- cross-module data migrations must be compatible with both the old and target
+  provider interface until activation finishes
+- rollback must restore the package set and database state together, or be
+  documented as forward-only with a tested recovery procedure
+- if two modules require mutually incompatible live-data states, the catalog
+  must publish an intermediate compatibility release rather than a circular
+  update chain
+
+The release catalog is the first safety gate for this. Generated catalogs mark
+modules with registered migrations as `requires_review` by default. Release
+authors should keep that value for ordinary reversible migrations, raise it to
+`forward_only` when database rollback requires restoring a snapshot, and raise
+it to `destructive` when the update removes or irreversibly rewrites persisted
+data. Forward-only and destructive entries must include `recovery_tested: true`
+and recovery notes after a verified restore or forward-recovery rehearsal. The
+admin install-plan UI exposes the safety level and lets operators record an
+explicit acknowledgement; preflight keeps acknowledged forward-only/destructive
+changes visible as warnings.
+
+In practice, circular dependencies are avoided by designing interfaces with
+compatibility windows and by publishing bridge releases. A bridge release keeps
+the old interface while introducing the new one, allowing dependent modules to
+move first; a later release can retire the old interface after every dependent
+module has a compatible target version. Use `current_version_min` and
+`current_version_max_exclusive` to make those direct-update windows explicit in
+the catalog, and set `bridge_release: true` on intermediate targets that exist
+primarily to carry installations safely across a compatibility gap.
+
+Trusted catalog keys are configured locally:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_FILE=/srv/govoplan/trust/catalog-keyring.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS='{"release-key-1":"<base64 public key>"}'
+```
+
+For development or tightly controlled deployments, a keyring can be read from a
+URL and cached:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_URL=https://govoplan.example/catalogs/v1/keyring.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_CACHE=/srv/govoplan/runtime/catalog-cache/keyring.json
+```
+
+Production installations should pin the trusted keyring locally or ship it
+through deployment configuration. Fetching trusted keys from the same public
+origin as the catalog is convenient, but that origin must not become the only
+trust root.
+
+## Dependency Audits
+
+Dependency vulnerability checks are documented in
+[`DEPENDENCY_AUDITS.md`](DEPENDENCY_AUDITS.md). The local audit runner is:
+
+```bash
+cd /mnt/DATA/git/govoplan
+bash tools/checks/check-dependency-audits.sh
+```
+
+The Gitea workflow in `govoplan/.gitea/workflows/dependency-audit.yml` runs the same
+check against release dependency refs on pushes, pull requests, and a weekly
+schedule.
+
+Keyring entries support:
+
+- `key_id`
+- `public_key` or `public_key_base64`
+- `status`: `active`, `next`, `retired`, `revoked`, or `disabled`
+- `not_before`
+- `not_after`
+
+Rotation process:
+
+1. Add the next public key to the local trusted keyring with status `next`.
+2. Publish catalogs signed by both current and next keys.
+3. Upgrade installations so the next key is locally trusted.
+4. Promote the next key to `active`.
+5. Retire the old key only after every supported installation trusts the new
+   key.
+6. Mark a compromised key `revoked` and publish a higher sequence catalog
+   signed by an uncompromised key.
+
+Use replay state in production:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG_SEQUENCE_STATE=/srv/govoplan/runtime/catalog-sequences.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_ENFORCE_SEQUENCE=true
+```
+
+Core records the accepted sequence per channel after a catalog entry is planned
+from the admin interface. With strict sequence enforcement, a previously
+accepted sequence is rejected; without strict enforcement, only older sequences
+are rejected. Catalogs should always expire.
+
+The sequence state file is operational state, not a trust root. Keep it on
+persistent storage and include it in normal backups:
+
+```json
+{
+  "channels": {
+    "stable": {
+      "last_sequence": 42,
+      "accepted_at": "2026-07-07T12:00:00Z",
+      "key_id": "release-key-1",
+      "source": "https://govoplan.example/catalogs/v1/channels/stable.json"
+    }
+  }
+}
+```
+
+If the file is lost, restore it from backup. If no backup exists, reconstruct
+each channel from the highest sequence already accepted in installer run
+records, release records, or the currently deployed module package set. Do not
+lower `last_sequence` to make an older catalog pass; publish a new higher
+sequence catalog when the accepted point is uncertain.
+
+If the file is corrupted, copy it aside for incident review, validate the
+current signed catalog with channel and freshness enforcement, then rewrite the
+state with the known accepted sequence. Keep
+`GOVOPLAN_MODULE_PACKAGE_CATALOG_REQUIRE_SIGNATURE=true` and approved-channel
+checks enabled during recovery. Temporarily disabling
+`GOVOPLAN_MODULE_PACKAGE_CATALOG_ENFORCE_SEQUENCE` allows revalidating the same
+sequence, but older sequences remain rejected once the reconstructed
+`last_sequence` is in place.
+
+Approved channels are deployment policy:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG_APPROVED_CHANNELS=stable,lts
+GOVOPLAN_MODULE_PACKAGE_CATALOG_REQUIRE_SIGNATURE=true
+```
+
+The admin UI can display other catalog metadata, but core rejects catalogs from
+unapproved channels when validation is configured.
+
+Catalog entries can require license features:
+
+```json
+"license_features": ["module.mail", "support.standard"]
+```
+
+Core checks those requirements against an offline license file before allowing
+the entry into the install plan.
+
+```bash
+GOVOPLAN_LICENSE_FILE=/srv/govoplan/license.json
+GOVOPLAN_LICENSE_ENFORCEMENT=true
+GOVOPLAN_LICENSE_TRUSTED_KEYS_FILE=/srv/govoplan/trust/license-keyring.json
+```
+
+License files are JSON objects with:
+
+- `license_id`
+- `subject`
+- `features`
+- `valid_from`
+- `valid_until`
+- `signature`
+
+Issue or renew a license from an operator/release shell that has the Ed25519
+private key:
+
+```bash
+govoplan-module-installer \
+  --issue-license /srv/govoplan/license.json \
+  --license-id customer-2026-07 \
+  --license-subject "Example Municipality" \
+  --license-feature module.mail \
+  --license-feature support.standard \
+  --license-valid-until 2027-07-31T23:59:59Z \
+  --license-signing-key-id license-issuer-1 \
+  --license-signing-private-key /srv/govoplan/secrets/license-issuer-1.pem \
+  --format json
+```
+
+Validate an imported license without exposing secrets:
+
+```bash
+govoplan-module-installer \
+  --validate-license /srv/govoplan/license.json \
+  --license-trusted-key license-issuer-1="<base64 public key>" \
+  --require-trusted-license \
+  --license-required-feature module.mail \
+  --format json
+```
+
+The CLI and admin module catalog panel report the license id, subject,
+validity window, signing key id, signed/trusted state, available features, and
+missing entitlements for the configured package catalog. They do not expose
+private signing material.
+
+License enforcement can run in observe-only mode by leaving
+`GOVOPLAN_LICENSE_ENFORCEMENT` unset. In that mode, missing or invalid license
+data is surfaced as a warning but does not block planning.
+
+Renewal is an ordinary re-issuance with a new `license_id`, extended
+`valid_until`, and the full intended feature set. Import the renewed JSON to
+`GOVOPLAN_LICENSE_FILE`, keep the previous file for audit, and validate it
+before setting enforcement.
+
+Revocation is handled through the trusted license keyring. Mark a compromised
+or invalid issuer key as `revoked` or `disabled`, publish or deploy the updated
+keyring, then reissue affected licenses with an active key. Installations that
+run with `GOVOPLAN_LICENSE_ENFORCEMENT=true` reject licenses signed only by a
+revoked key after the local keyring is updated.
+
+Emergency fallback is deliberately explicit. Operators can temporarily unset
+`GOVOPLAN_LICENSE_ENFORCEMENT` to keep package planning observable while a
+license or keyring is recovered. Record the change in the operational incident
+log, keep catalog signature and channel enforcement enabled, and restore
+license enforcement after a trusted renewal validates successfully.
+
+Licensing is intentionally separate from open-source code licensing. The
+catalog/license mechanism can govern support channels, official release
+eligibility, hosted update access, professional support, or commercial
+entitlements without changing the source license of the repositories.
+
+Production-grade distribution still needs remote registry/git artifact
+resolution before package-manager apply, a hardened catalog publishing pipeline
+that writes to `addideas-govoplan-website`, and automated key rotation and
+emergency revocation drills.
+
+## Release Catalog Publishing
+
+GovOPlaN release catalogs are published to `addideas-govoplan-website` as
+static JSON and verified by `govoplan-core` before installer plans are
+accepted. Private signing keys must stay outside all git repositories. Public
+keyrings are published with the website.
+
+Create the first catalog signing key on the release machine:
+
+```bash
+cd /mnt/DATA/git/govoplan
+KEY_DIR="$HOME/.config/govoplan/release-keys"
+mkdir -p "$KEY_DIR"
+./.venv/bin/python tools/release/generate-catalog-keypair.py \
+  --key-id release-key-1 \
+  --private-key "$KEY_DIR/release-key-1.pem" \
+  --public-key "$KEY_DIR/release-key-1.pub" \
+  --keyring "$KEY_DIR/catalog-keyring.json"
+```
+
+Keep `release-key-1.pem` private. The generated keyring contains only public
+material.
+
+Generate the signed catalog into `addideas-govoplan-website`:
+
+```bash
+cd /mnt/DATA/git/govoplan
+KEY_DIR="$HOME/.config/govoplan/release-keys"
+tools/release/publish-release-catalog.sh \
+  --version <x.y.z> \
+  --sequence 202607071340 \
+  --catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem" \
+  --build-web
+```
+
+This writes:
+
+- `/mnt/DATA/git/addideas-govoplan-website/public/catalogs/v1/channels/stable.json`
+- `/mnt/DATA/git/addideas-govoplan-website/public/catalogs/v1/keyring.json`
+
+The wrapper validates the catalog with core using the generated public keyring.
+
+For normal module/core releases, first audit and record migration baselines,
+then tag and push the module/core repos. Finally publish the website catalog:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python tools/release/release-migration-audit.py --strict
+```
+
+```bash
+cd /mnt/DATA/git/govoplan
+KEY_DIR="$HOME/.config/govoplan/release-keys"
+tools/release/publish-release-catalog.sh \
+  --version <x.y.z> \
+  --catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem" \
+  --build-web \
+  --commit \
+  --tag \
+  --push
+```
+
+The website tag is `catalog-v<x.y.z>`. The public URL is:
+
+```text
+https://govoplan.add-ideas.de/catalogs/v1/channels/stable.json
+```
+
+The public keyring URL is:
+
+```text
+https://govoplan.add-ideas.de/catalogs/v1/keyring.json
+```
+
+`/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh` can publish the web catalog after module and core
+tags have been pushed. It runs the migration release audit in automatic mode:
+warning-only before the first recorded migration baseline, strict after a
+baseline exists. Add `--strict-migration-audit` when you want to force strict
+mode explicitly:
+
+```bash
+cd /mnt/DATA/git/govoplan
+KEY_DIR="$HOME/.config/govoplan/release-keys"
+tools/release/push-release-tag.sh \
+  --bump subversion \
+  --strict-migration-audit \
+  --publish-web-catalog \
+  --catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem" \
+  --build-web-catalog
+```
+
+Use `--catalog-signing-key` more than once during a key rotation window. The
+catalog will contain multiple signatures and the public keyring will include the
+corresponding public keys.
+
+## Release Doctor
+
+Use `/mnt/DATA/git/govoplan/tools/release/release-doctor.py` before release preparation and again before
+publishing. It inspects repository state, local versions, release tags,
+migration audit state, release package refs, stable catalog/keyring state, and
+optionally public catalog availability. The default mode is read-only and
+offline. Status output is intentionally concise:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python tools/release/release-doctor.py status --target-version <x.y.z>
+```
+
+Use `--details` when the full findings should be printed directly:
+
+```bash
+./.venv/bin/python tools/release/release-doctor.py status --target-version <x.y.z> --details
+```
+
+For concise guidance, print only suggested next commands:
+
+```bash
+./.venv/bin/python tools/release/release-doctor.py next --target-version <x.y.z>
+```
+
+For an operator-guided session, run interactive mode. The doctor asks which
+suggested command to run; mutating commands require typing `RUN` before they
+execute:
+
+```bash
+./.venv/bin/python tools/release/release-doctor.py interactive --target-version <x.y.z>
+```
+
+Interactive mode starts with a compact summary and waits for an action. It can
+open the full report in the configured pager, run one suggested command, repair
+Git `safe.directory` dubious-ownership blocks after explicit confirmation, push
+all clean repositories that are ahead of their upstream, or commit and push all
+dirty repositories. The dirty-repository bulk action asks for a commit message,
+skips repositories that are behind upstream, and requires typing
+`COMMIT AND PUSH` before it stages, commits, and pushes.
+
+Add `--online` when remote tag and public catalog/keyring reachability should be
+checked. Add `--json` when a CI job or another tool should consume the report.
+
+On a GovOPlaN installation that should consume the official stable catalog:
+
+```bash
+GOVOPLAN_MODULE_PACKAGE_CATALOG_URL=https://govoplan.add-ideas.de/catalogs/v1/channels/stable.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_CACHE=/srv/govoplan/runtime/catalog-cache/stable.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_REQUIRE_SIGNATURE=true
+GOVOPLAN_MODULE_PACKAGE_CATALOG_APPROVED_CHANNELS=stable
+GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_FILE=/srv/govoplan/trust/catalog-keyring.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_SEQUENCE_STATE=/srv/govoplan/runtime/catalog-sequences.json
+GOVOPLAN_MODULE_PACKAGE_CATALOG_ENFORCE_SEQUENCE=true
+```
+
+For production, copy the public keyring into deployment configuration and pin it
+locally. Do not rely on a URL-fetched keyring as the only trust root.
+
+`stable.json` includes a top-level `core_release` section for operator/update
+tooling. Core is intentionally not listed as a normal module entry because it
+must not be added to saved enabled-module state. Core upgrades should remain an
+operator-supervised package update with restart and health checks.
+
+Key rotation for published catalogs:
+
+1. Generate the next private key outside git.
+2. Run `/mnt/DATA/git/govoplan/tools/release/publish-release-catalog.sh` with both signing keys.
+3. Publish the web catalog/keyring.
+4. Roll the new public keyring into installations.
+5. Stop signing with the old key after the supported fleet trusts the new key.
+6. Mark compromised keys as revoked in the public keyring and publish a higher
+   sequence catalog signed by a trusted uncompromised key.
+
+## PostgreSQL Release Check
+
+Release candidates should pass a disposable PostgreSQL migration and startup
+smoke check before tagging or publishing catalogs. Start the local testbed,
+then run the permutation check from the core checkout:
+
+```bash
+cd /mnt/DATA/git/govoplan/dev/postgres
+cp .env.example .env
+docker compose --env-file .env up -d
+
+cd /mnt/DATA/git/govoplan
+set -a
+. /mnt/DATA/git/govoplan/dev/postgres/.env
+set +a
+tools/checks/postgres-integration-check.py \
+  --database-url "$GOVOPLAN_POSTGRES_DATABASE_URL" \
+  --reset-schema
+```
+
+The script checks migrations and `/health` startup for core-only, files-only,
+mail-only, campaign-only, campaign+files, campaign+mail, and full-product
+module sets. `--reset-schema` is destructive and must only be used against a
+throwaway database.
+
+## Migration Baselines
+
+Development migrations may be small and numerous while a feature is moving.
+GovOPlaN keeps those detailed migrations on an explicit development track and
+publishes reviewed release shortcuts on the release track. Before a stable
+release, unreleased development migrations may be squashed into a release-level
+baseline or release-to-release upgrade migration. After a release tag has
+shipped, released migration revision IDs are immutable.
+
+The release policy is:
+
+- unreleased development migrations live in `dev_versions` and are not deleted
+  when a release shortcut is added;
+- released migrations live in `versions` and are never rewritten or deleted;
+- future release shortcuts are additive. A new release-to-release migration
+  starts from the previous recorded release heads, so installations can upgrade
+  through sane release steps instead of replaying every development revision;
+- each stable release records the public migration head revisions in
+  `docs/migration-release-baselines.json`;
+- `heads` records the Alembic dependency-leaf graph heads for a full graph,
+  while `owner_heads` records the latest migration revision per migration
+  owner for subset installs and review;
+- fresh installations should apply release-level baselines/upgrades, not
+  unreleased create-then-rename churn;
+- release-to-release schema changes should be folded into one reviewed
+  migration per migration owner where practical.
+
+The default runtime track is `release`:
+
+```bash
+cd /mnt/DATA/git/govoplan
+GOVOPLAN_MIGRATION_TRACK=release ./.venv/bin/python -m govoplan_core.commands.init_db
+```
+
+Use `dev` only for local/disposable development databases that intentionally
+need the detailed chain:
+
+```bash
+cd /mnt/DATA/git/govoplan
+GOVOPLAN_MIGRATION_TRACK=dev ./.venv/bin/python -m govoplan_core.commands.init_db
+```
+
+Production, release checks, operator install flows, and the normal development
+launcher should stay on the `release` track unless a fresh/disposable database
+is intentionally being used to test the detailed development chain.
+
+Audit the current graph during release preparation:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python tools/release/release-migration-audit.py
+```
+
+Audit the detailed development graph separately when a squash is prepared:
+
+```bash
+./.venv/bin/python tools/release/release-migration-audit.py --track dev
+```
+
+Generate the reviewed/manual squash checklist:
+
+```bash
+./.venv/bin/python tools/release/release-migration-audit.py --squash-plan
+```
+
+After the release migrations have been reviewed and the graph is final, record
+the release baseline:
+
+```bash
+./.venv/bin/python tools/release/release-migration-audit.py --record-release <x.y.z>
+```
+
+Use strict mode to verify that the current heads are recorded:
+
+```bash
+./.venv/bin/python tools/release/release-migration-audit.py --strict
+```
+
+`/mnt/DATA/git/govoplan/tools/release/push-release-tag.sh` runs the audit by default in automatic mode:
+non-strict while no release baseline exists, strict after the first baseline is
+recorded. Pass `--warn-migration-audit` for an explicit non-strict audit,
+`--strict-migration-audit` to force strict mode, or `--skip-migration-audit`
+only for emergency/manual release work.
+
+The first public baseline is v0.1.7. It intentionally adds release-track
+shortcuts for the unreleased v0.0.0 -> v0.1.7 development chains while keeping
+the detailed chains on the `dev` track. No production installations existed
+before that baseline, so pre-v0.1.7 development revisions are not release
+upgrade targets. Future release-to-release changes must start from a recorded
+release baseline and add a new release-track step-up instead of replacing prior
+release shortcuts. The tracking issue is
+`add-ideas/govoplan-core#223`.
+
+## Related Operator Documents
+
+- `DEPLOYMENT_OPERATOR_GUIDE.md`: runtime environment, explicit migrations,
+  backup/restore commands, module installer daemon/supervisor operation, and
+  rollback drills.
+- `REMOTE_WEBUI_BUNDLES.md`: experimental browser-loaded module bundles for
+  controlled deployments; normal releases use package builds.
 
 ## Release Checklist
 
 - Keep Python package versions, WebUI package versions, and git tags aligned.
-- Tag core, files, mail, and campaign repositories together.
-- Update `requirements-release.txt` and `webui/package.release.json` when the release tag changes.
-- Generate release lockfiles from release manifests in a clean build workspace.
+- Tag core, access, admin, tenancy, policy, audit, files, mail, campaign,
+  calendar, and scaffold module repositories together.
+- Update meta `requirements-release.txt` and core `webui/package.release.json` when the
+  release tag changes.
+- Generate the committed full-product release lockfile from
+  `package.release.json` with `/mnt/DATA/git/govoplan/tools/release/generate-release-lock.sh`.
+- Run `/mnt/DATA/git/govoplan/tools/release/release-migration-audit.py --strict` after recording a release
+  baseline.
+- Run the PostgreSQL release check against a disposable database.
+- Publish the signed catalog through the release catalog publishing flow above.
+- Add separate release manifest/lockfile pairs only for module compositions
+  that are shipped as their own products.
 - Do not commit local sibling paths into release manifests.

docs/REMOTE_WEBUI_BUNDLES.md

@@ -0,0 +1,161 @@
+# Remote WebUI Bundle Loading
+
+GovOPlaN WebUI modules normally ship through the core WebUI package graph:
+install a tagged npm/git dependency, run `npm install`, rebuild the shell, and
+restart or reload the served assets. Remote WebUI bundles are an experimental
+future path for controlled deployments where a backend-enabled module is not in
+the local WebUI package graph and the operator wants the shell to load its
+frontend without rebuilding core.
+
+This design defines the target guardrails. The current rebuild/reload path
+remains the default production path.
+
+## Current Rebuild Path
+
+The supported release path is:
+
+1. Install or remove backend and WebUI package dependencies through the trusted
+   installer CLI/daemon.
+2. Snapshot package state before mutation.
+3. Run `npm install` and optionally `npm run build`.
+4. Restart or reload the served WebUI assets.
+5. Use installer rollback if package apply, restart, or health checks fail.
+
+Strengths:
+
+- package manager and lockfile semantics stay conventional
+- CSP can stay strict because all code is served as built assets
+- rollback restores package files and lockfiles
+- local development uses sibling workspace dependencies naturally
+
+Costs:
+
+- frontend changes require a rebuild/reload
+- hot enabling a module with frontend code is not possible in the running shell
+- failed rebuilds happen at install time, not at lazy module-load time
+
+## Remote Bundle Path
+
+Remote loading is only for modules that are enabled by the backend and absent
+from `virtual:govoplan-installed-modules`. The backend manifest exposes:
+
+- `FrontendModule.asset_manifest`
+- `asset_manifest_integrity`
+- `asset_manifest_signature`
+- `asset_manifest_public_key_id`
+- `asset_manifest_contract_version`
+
+The WebUI shell fetches the asset manifest, verifies manifest integrity and/or
+signature, validates the manifest contract, fetches the entry bundle, verifies
+the entry integrity, imports the bundle, validates the exported
+`PlatformWebModule`, and applies backend metadata before registering routes,
+navigation, and UI capabilities.
+
+Unsigned and unhashed manifests are skipped. Entries without integrity are
+skipped. A module id mismatch is skipped.
+
+## Asset Manifest Contract
+
+Contract version `1`:
+
+```json
+{
+  "contractVersion": "1",
+  "moduleId": "files",
+  "entry": "./files-webui.remote.js",
+  "entryIntegrity": "SHA-256-<base64-or-hex-digest>",
+  "moduleExport": "default"
+}
+```
+
+The backend manifest carries the manifest-level trust metadata. The remote
+asset manifest carries the concrete entry URL and entry digest.
+
+## Compatibility Checks
+
+Before a remote bundle is accepted:
+
+- backend module must be enabled
+- local WebUI module with the same id must be absent
+- manifest contract must be supported by the shell
+- manifest `moduleId`, exported module `id`, and backend module id must match
+- backend metadata remains authoritative for label, version, dependencies,
+  nav, and runtime UI capability exposure
+- future contract versions must declare required shell capabilities so old
+  shells fail closed
+
+Remote bundles must not broaden backend permissions. They can only contribute
+routes/nav/capabilities that the backend metadata and existing permission
+checks allow.
+
+## CSP
+
+The current implementation imports verified entry bytes through a blob URL. A
+production CSP for this mode must explicitly allow:
+
+- `connect-src` for the approved asset-manifest and bundle origins
+- `script-src` for `blob:` only when remote loading is enabled
+- no `unsafe-inline` requirement for remote modules
+
+If an installation cannot allow `blob:` scripts, the follow-up implementation
+should use signed same-origin module assets with static URLs instead of blob
+imports. Remote loading must be disableable by configuration so strict-CSP
+deployments can keep the rebuild path only.
+
+## Cache Invalidation
+
+The shell cache key is:
+
+```text
+<module-id>:<asset-manifest-url>:<backend-module-version>
+```
+
+Release catalogs should publish immutable manifest and entry URLs or change at
+least one cache-key component on every release. Emergency rollback can point the
+backend manifest at a previous immutable manifest URL or lower the enabled
+module version after the backend package rollback.
+
+Browsers may still cache remote responses. Approved asset servers should use:
+
+- long cache lifetimes only for content-addressed immutable assets
+- short cache lifetimes or explicit revalidation for channel/latest manifest
+  aliases
+- `Cache-Control: no-store` for emergency override manifests
+
+## Rollback
+
+Remote WebUI rollback is metadata rollback, not package-manager rollback:
+
+- if the backend package install rolls back, the previous backend frontend
+  metadata returns
+- if only remote assets are bad, publish a new manifest URL or revert the
+  backend/frontend metadata to the last known good manifest
+- failed remote loading must degrade by omitting the remote module frontend,
+  not by breaking the shell
+
+Installer run records should eventually include remote asset manifest URLs,
+integrity, signature key ids, and load-test results when a plan enables a
+remote frontend.
+
+## Local And Development Behavior
+
+Local development should keep using workspace/file dependencies and Vite. Remote
+loading is useful for integration testing release artifacts, not for day-to-day
+module UI development.
+
+Development deployments may use unsigned catalogs and local asset servers only
+when signature/integrity enforcement is intentionally disabled. The remote
+loader itself still requires an integrity hash or a verifiable signature.
+
+## Follow-Up Slices
+
+1. Add a server-side remote-bundle policy flag and surface whether remote
+   loading is enabled in platform metadata.
+2. Add CSP documentation/config generation for strict rebuild-only mode versus
+   controlled remote-bundle mode.
+3. Add an installer/catalog preflight that validates remote WebUI asset
+   manifests and records verified identity in installer run records.
+4. Add Playwright coverage for a signed test remote bundle, failed digest, bad
+   module id, cache-key refresh, and fallback when the module is unavailable.
+5. Add release tooling to emit immutable remote asset manifests with digest,
+   signature, key id, and rollback metadata.

docs/SECURITY_AUDIT.md

@@ -0,0 +1,15 @@
+# Security Audit Toolchain
+
+The shared GovOPlaN security audit toolbox moved to the meta repository.
+
+Use:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/checks/security-audit/run.sh --mode ci --scope govoplan
+tools/checks/security-audit/run.sh --mode full --scope govoplan
+```
+
+Canonical documentation:
+
+- `/mnt/DATA/git/govoplan/docs/SECURITY_AUDIT.md`

docs/SELF_HOSTED_INSTALLABILITY.md

@@ -0,0 +1,80 @@
+# Self-Hosted Installability
+
+GovOPlaN uses a staged self-hosted installability path.
+
+## Packaging Decision
+
+The early packaging approach is a staged combination:
+
+1. Generate an explicit environment template and validate it before startup.
+2. Use a Compose-backed production-like development profile for local rehearsal.
+3. Use the deployment operator guide as the runbook for migrations, workers,
+   backups, health checks, and module installer rollback drills.
+4. Use the module installer CLI/daemon for package mutation once the runtime is
+   already installed and under maintenance mode.
+
+This keeps first installation understandable while still preserving the later
+goal of install/update/uninstall through signed catalogs and the installer
+daemon. The API server must not run package managers from request handlers.
+
+## Config Bootstrap
+
+Generate a self-hosted template:
+
+```bash
+cd /mnt/DATA/git/govoplan
+./.venv/bin/python -m govoplan_core.commands.config env-template \
+  --profile self-hosted \
+  --generate-secrets \
+  --output .env.self-hosted
+```
+
+Validate the current shell environment:
+
+```bash
+set -a
+. .env.self-hosted
+set +a
+./.venv/bin/python -m govoplan_core.commands.config validate --profile self-hosted
+```
+
+The command reports all known blockers at once. Production-like/self-hosted
+profiles require explicit `APP_ENV`, `DATABASE_URL`, `MASTER_KEY_B64`,
+`ENABLED_MODULES`, and `CORS_ORIGINS`. Production rejects SQLite, development
+bootstrap, insecure auth cookies, and unsigned catalog trust roots when a
+catalog source is configured.
+
+## Production-Like Dev Stack
+
+Use the local production-like wrapper for repeatable rehearsal:
+
+```bash
+cd /mnt/DATA/git/govoplan
+tools/launch/production-like-dev.sh validate-config
+tools/launch/production-like-dev.sh seed
+tools/launch/production-like-dev.sh start
+```
+
+Stop Docker dependencies:
+
+```bash
+tools/launch/production-like-dev.sh stop
+```
+
+Reset all profile data:
+
+```bash
+tools/launch/production-like-dev.sh reset --yes
+```
+
+The start command delegates to `tools/launch/launch-production-like-dev.sh`, which
+runs API, worker, and WebUI in the foreground. Stop those processes with
+`Ctrl+C` in the launcher terminal.
+
+## Module Boundary Gate
+
+`govoplan/tools/checks/check_dependency_boundaries.py` is part of the focused verification
+path. It checks backend imports and WebUI package/source imports so modules do
+not grow hidden runtime dependencies on each other. Feature modules should
+integrate through core capabilities, backend APIs/events, route contributions,
+or explicit UI extension points.

docs/SYSTEM_GOVERNANCE_MANIFEST.md

@@ -1,178 +0,0 @@
-# Multi Seal Mail - Current System and Tenant Governance Model
-
-**Updated:** 2026-06-16
-**Current migration head:** `f5a6b7c8d9e0`
-
-## Governance Rule
-
-System policy is authoritative for tenants and all lower levels. Each lower level may only narrow what it inherits:
-
-```text
-system
--> tenant
--> user or group owner
--> campaign
-```
-
-Lower levels do not widen privileges, allowed profiles, retention durations or credential rights granted by a higher level.
-
-## Administration Structure
-
-```text
-SYSTEM
-- Settings
-- Retention
-- Mail servers
-- Tenants
-- Users
-- Groups
-- System roles
-- Tenant roles
-- Audit
-
-TENANT
-- Settings boundary
-- Users
-- Groups
-- Roles
-- API keys
-- Mail servers
-- Retention
-- Audit
-
-USER
-- User mail
-- User retention
-
-GROUP
-- Group mail
-- Group retention
-```
-
-There is no separate System access page. Compatibility access scopes remain in the backend for assignment/read boundaries.
-
-## Tenant Governance
-
-System settings define tenant defaults and whether tenants may narrow selected options. Tenant overrides can only restrict:
-
-- custom groups;
-- custom roles;
-- tenant API keys.
-
-The backend enforces that tenant governance cannot widen system-denied privileges.
-
-## Mail-Profile Governance
-
-Mail server profiles may exist at these scopes:
-
-```text
-system
-tenant
-user
-group
-campaign
-```
-
-Effective campaign profile availability follows campaign ownership. A campaign owned by a user resolves through system, tenant, that user and campaign policy. A group-owned campaign resolves through system, tenant, that group and campaign policy.
-
-Policy semantics:
-
-- higher levels define the maximum available profile set;
-- lower levels can further restrict the set;
-- forced profiles mean the lower level must choose from the forced set;
-- a forced set with one profile effectively enforces that profile;
-- campaign-level profile creation is allowed only if the effective policy permits it;
-- credentials may be inherited from the authoritative profile or supplied by a lower level only when override is allowed;
-- deny patterns always win over allow patterns;
-- empty or `*` allowlist means allow all except denied;
-- non-empty allowlist means at least one allow rule must match and no deny rule may match.
-
-Pattern targets:
-
-```text
-SMTP hostname
-IMAP hostname
-envelope sender
-From header
-recipient domains
-```
-
-Ownership transfer is intentionally deferred as a two-step workflow: original owner initiates, new owner accepts and reselects/repairs the mail profile if their effective policy requires it.
-
-## Retention Governance
-
-Retention policy is hierarchical:
-
-```text
-system -> tenant -> user/group -> campaign
-```
-
-Managed fields:
-
-- raw campaign JSON retention days;
-- generated EML retention days;
-- stored report detail retention days;
-- mock mailbox retention days;
-- audit detail retention days.
-
-Rules:
-
-- system may set concrete defaults or unlimited retention;
-- system exposes allow-limiting toggles per field;
-- tenants, users/groups and campaigns may only shorten inherited retention where the parent allows limiting;
-- blank lower-level values inherit;
-- mock mailbox retention is currently system-level because mock mailbox records do not yet carry tenant/campaign ownership metadata;
-- dry-run/apply retention actions report affected classes before destructive cleanup.
-
-## Role Definitions and Assignments
-
-### System roles
-
-System roles define instance-wide permissions. `system:*` is stored as one wildcard and displayed as granting the full system catalogue. System owner is protected.
-
-### Tenant roles
-
-Tenant roles can be system-governed templates or tenant-local definitions, subject to system tenant-governance settings and actor delegation ceilings. Wildcard counts are expanded against the canonical tenant catalogue.
-
-## Audit Access
-
-Audit access remains scope-separated:
-
-```text
-system audit -> system:audit:read
-tenant audit -> active tenant + audit:read
-```
-
-Audit pages use server pagination, filtering and bounded grids.
-
-## Tenant Switching
-
-Tenant switching preserves the current URL when possible and falls back when a route/resource is not accessible in the new tenant context.
-
-The tenant selector is hidden for ordinary single-tenant accounts and visible for multi-tenant or system tenant-management contexts.
-
-## DataGrid Contract in Administration
-
-Admin lists use bounded container grids:
-
-- one flexible fill column;
-- fixed total table width;
-- compact action/status/count columns;
-- resizable text/date columns;
-- no intrinsic content growth;
-- sticky headers where needed;
-- server pagination for audit.
-
-## Still Deferred
-
-- real SMTP/IMAP test-bed verification and operator runbook;
-- recipient import with column mapping;
-- Seafile/external connector governance;
-- system/tenant/group/user file-space hierarchy and external storage hierarchy;
-- session/device revocation UI;
-- backup/restore, monitoring and update procedures;
-- DSAR workflows and evidence bundle verifier;
-- campaign ownership transfer workflow;
-- policy impact analysis before delete/disable/unshare/change;
-- LDAP/OIDC/SAML provisioning;
-- destructive tenant erasure orchestration.

docs/UI_UX_DECISION_LEDGER.md

@@ -0,0 +1,216 @@
+# GovOPlaN UI/UX Decision Ledger
+
+This ledger records product UI/UX decisions that affect admin, settings,
+configuration, connector, policy, and module-management surfaces. It is a
+binding design reference: future implementation should follow these decisions
+unless the decision is explicitly revised here and affected screens are updated
+to match.
+
+Active tracking issue: `add-ideas/govoplan-core#225`.
+
+## Operating Rule
+
+GovOPlaN must expose advanced platform capability without presenting the user
+with every option at once. Non-technical users should be able to complete common
+workflows through guided, plain-language flows. Expert and diagnostic detail may
+exist, but it must be deliberately layered.
+
+The ethical design doctrine in `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` is the
+normative baseline for this ledger. A screen can be visually quiet and still be
+ethically complete only when it preserves context, consequence,
+contestability, responsibility, and traceability at the point of action.
+
+## Binding Decisions
+
+| ID | Decision | Status | Applies To |
+| --- | --- | --- | --- |
+| UX-001 | Use progressive disclosure by default. Common decisions stay visible; advanced or hazardous options live in collapsed panels, later wizard steps, or explicit advanced sections. | Accepted | Admin, settings, connector setup, policy editors, module operations |
+| UX-002 | Raw JSON is not a primary configuration editor. Every normal configuration path needs typed controls, validation, and help text. JSON may be shown for import/export, diagnostics, or expert inspection only. | Accepted | All admin/configuration UIs |
+| UX-003 | Prefer guided workflows over option dumps for setup and risky changes. Use wizards for connector setup, configuration package import, module install/uninstall, destructive actions, and policy changes with broad impact. | Accepted | Connectors, package import, module lifecycle, governance/policy |
+| UX-004 | Discover technical values when possible. Ask for the smallest user-known input, then discover and prefill technical fields for review. | Accepted | File connectors, mail/groupware, public URLs, future external providers |
+| UX-005 | Disabled actions and failed steps must explain why they are unavailable, who can fix them, and where to go next. Silent disabled states are not acceptable for primary actions. | Accepted | All primary actions |
+| UX-006 | Explanations must be available but quiet. Use short inline text and expose richer explanations through help affordances, side panels, expandable sections, or review steps. | Accepted | All complex forms and flows |
+| UX-007 | Creation/editing should prefer modals or focused step flows when it reduces page clutter. Overview and comparison screens remain full-page. | Accepted | Settings/admin surfaces |
+| UX-008 | Similar concepts must use shared placement and components: server/credential/policy rows, problem lists, review steps, advanced panels, confirmation modals, and empty/error states. | Accepted | Core WebUI and module WebUIs |
+| UX-009 | Preflight and diagnostics are product UX. Validation, policy, permission, dependency, and capability failures must be written for operators before exposing internal details. | Accepted | Installer, connectors, policy, package import |
+| UX-010 | Context, decision, and consequence must be visible together for actions that affect rights, duties, records, money, communication, retention, external systems, or workflow state. | Accepted | Workflow, admin, portal, policy, connector, records, payments |
+| UX-011 | Navigation is not consent. Route changes, panel switches, and passive selection must not execute consequential actions without an explicit action surface. | Accepted | All WebUI surfaces |
+| UX-012 | Automated actions must remain inspectable. The UI must show the system actor, trigger, policy result, observed effects, and failure/manual-intervention state when automation changes administrative state. | Accepted | Workflow, automation, connectors, tasks, audit |
+| UX-013 | Contestable decisions must expose provenance. Denials, locks, generated outputs, calculated defaults, policy decisions, access decisions, and retention decisions need a reachable source path. | Accepted | Policy, access, templates, workflow, retention, records |
+| UX-014 | Retraction, expiry, undo, rollback, and delete controls must state the real limit of the operation. Corrective or future-only actions must not be described as if they undo already observed effects. | Accepted | Postbox, files, records, installer, workflow, payments |
+
+## Confirmed Implementation Decisions
+
+These decisions were accepted on 2026-07-09 for the first implementation slice.
+They shape reusable components and screen structure. Future changes must revise
+this section and update affected screens.
+
+### DUE-001: Primary Admin Configuration Shell
+
+Decision: admin/configuration surfaces should standardize on a two-zone layout.
+
+- Left or top area: searchable overview/list, status, and primary actions.
+- Main area: selected item summary and common settings.
+- Modal/wizard: create, connect, edit, test, review, and confirm actions.
+- Collapsed advanced panels: rarely used technical fields.
+
+Use this for file connectors and mail servers first, then migrate policy,
+retention, API keys, and module operations.
+
+### DUE-002: Wizard Step Model
+
+Decision: standard wizard steps and names use this baseline:
+
+1. Choose type or scope.
+2. Enter essentials.
+3. Discover or test.
+4. Configure ownership and policy.
+5. Review changes and blockers.
+6. Save or submit for operator action.
+
+Not every wizard needs every step, but flows should use these names and order
+where applicable.
+
+This applies to explicit assisted setup, onboarding, import, preflight, and
+risky multi-step operations. It is not the default shape for ordinary create or
+edit dialogs.
+
+### DUE-003: Explanation Placement
+
+Decision: richer explanations should use this placement model:
+
+- Short helper text below labels only when it prevents common mistakes.
+- Tooltips for icon-only controls and compact terms.
+- Expandable "Why?" or "Details" blocks for contextual explanations.
+- Right-side detail panel or review step for preflight/provenance/diagnostics.
+
+Avoid permanently visible paragraphs inside dense admin cards.
+
+### DUE-004: Advanced Options Contract
+
+Decision: advanced options are fields that are needed for control, compatibility,
+or diagnostics but are not part of the common setup path.
+
+- protocol-specific endpoints, ports, path overrides, TLS/signing toggles,
+  timeout/retry tuning, raw headers, migration/destructive flags, and fallback
+  compatibility settings are advanced.
+- names, descriptions, provider type, base URL, ownership, policy mode, and
+  basic credentials are not advanced.
+
+Advanced fields must still be editable through typed controls.
+
+### DUE-005: Blocker Language Contract
+
+Decision: all disabled or blocked primary actions should use a shared structured
+reason object.
+
+Shape:
+
+- `summary`: short plain-language reason.
+- `details`: optional explanation.
+- `required_action`: what needs to happen.
+- `actor`: who can do it, for example system administrator or tenant admin.
+- `target`: where to go or which setting/capability is missing.
+- `technical_details`: optional expandable developer/operator data.
+
+For simple missing required fields, highlight the fields and put the structured
+reason in a compact hover/focus bubble on the disabled primary action instead of
+adding a large persistent warning block.
+
+### DUE-006: First Migration Surface
+
+Decision: convert file connectors first, then mail servers. They share the same
+server/credential/policy model, are high-value, and will prove the reusable
+patterns quickly.
+
+### DUE-007: Adaptive Create/Edit Forms
+
+Decision: ordinary create/edit dialogs should show the full editable state in an
+adaptive form, not force a linear wizard.
+
+- The user chooses a type, provider, credential mode, or policy mode.
+- The dialog immediately adjusts to show only the fields relevant to that state.
+- Editing an existing object uses the same field grouping and layout as creating
+  it, so users can recognize the state they configured.
+- Discovery and test actions must give visible feedback in the same dialog:
+  directly usable, discovered alternative, credentials needed/rejected, or not
+  found with the next action the user can take.
+- Wizard shells remain available for assisted setup, first-run guidance,
+  imports, discovery-heavy flows, and operational preflight workflows.
+
+## Implementation Sequence
+
+| Phase | Scope | Output |
+| --- | --- | --- |
+| 0 | UX inventory | List every admin/settings/configuration surface, classify it, and record whether it violates a binding decision. |
+| 1 | Core primitives | Shared wizard shell, advanced panel, help affordance, blocker callout, problem list, review step, and discovery/test result components. |
+| 2 | File connectors | Adaptive create/edit for provider/server, credential, discovery/test, ownership/policy, plus optional assisted wizard later. |
+| 3 | Mail servers | Same adaptive pattern as files, adapted to server/credential/policy and test-send/test-login behavior. |
+| 4 | Policy/retention editors | Effective value first, provenance visible, override/edit in modal, blocked edits explained. |
+| 5 | Module/package operations | Step-based install/uninstall flow with preflight, maintenance, daemon handoff, migration, and rollback explanation. |
+| 6 | Remaining settings/admin screens | Apply inventory findings by priority and remove one-off layouts. |
+
+## Current Surface Inventory
+
+This is the phase-0 inventory baseline. It should be extended as each screen is
+converted or reviewed.
+
+| Surface | Repository | UX State | Next Action |
+| --- | --- | --- | --- |
+| File connector settings | `govoplan-files` | First adaptive modal slice started: connections and credentials now use full-state create/edit forms with conditional fields, advanced panels, and blocker primitives. Wizard shell is retained for later assisted setup. Central policy card still needs a layered editor. | Finish provider discovery/test-in-flow, then convert policy editing. |
+| Mail server settings | `govoplan-mail` / `govoplan-core` | Uses the shared server/credential model visually, but create/edit still needs the same adaptive pattern as files. | Migrate to adaptive server/credential/policy dialogs, with optional assisted wizard later. |
+| Connector policy/effective rows | `govoplan-core`, module UIs | Effective-policy direction exists, but many editors still expose broad option sets. | Put effective value first, move overrides into modal, and explain blocked edits. |
+| Admin module management | `govoplan-admin` | Has preflight concepts, but operational choices are still technical and dense. | Convert install/uninstall/package changes to operator wizards. |
+| Configuration packages | `govoplan-admin` | Catalog/import work exists, but package editing can still drift toward technical fields. | Add guided import/review/problem-list flow. |
+| Retention and privacy | `govoplan-core` | Functional editor exists; consequence language and provenance can be stronger. | Layer advanced retention options and add review for broad changes. |
+| API keys | `govoplan-access` / admin UI | Security-sensitive creation needs least-privilege guidance. | Add scoped creation wizard with expiry/owner review. |
+| User settings | `govoplan-core` | Preferences persistence exists; interface navigation issue was fixed earlier, but the surface still needs UX review. | Keep simple sections, remove double-click traps, and add quiet explanations. |
+
+## Impact Index
+
+| Surface | Current Risk | Expected Pattern |
+| --- | --- | --- |
+| File connectors | Too many technical fields and unclear setup order. | Adaptive create/edit form with optional assisted wizard, discovery/test, credential binding, policy review, and advanced protocol panel. |
+| Mail servers | Similar server/credential/policy concepts risk diverging from files. | Same tree/list and adaptive server/credential/policy model as file connectors. |
+| Connector credentials | Security-sensitive details can overwhelm users. | Separate credential flow with secret-reference language and test result explanation. |
+| Policy and effective settings | Users need to know why a value is inherited or locked. | Effective row first, source/provenance, local override action, actionable blocked reason. |
+| Module install/uninstall | Operationally risky, currently inherently technical. | Operator wizard with preflight, maintenance, daemon handoff, review, and rollback explanation. |
+| Configuration packages | Could become package JSON editing. | Package catalog/import wizard using provider data requirements and problem lists. |
+| Retention/privacy | High-risk settings need explanation and provenance. | Layered editor with plain-language consequences and review. |
+| Automation/workflow commands | Hidden side effects would undermine accountability. | Action/effect preview, system-actor display, command record, retry/quarantine/manual states, and audit links. |
+| Postbox and encrypted communication | Retraction and access can be misunderstood. | Honest key-fetch/decryption state, expiry limits, recipient/device access provenance, and delivery evidence. |
+| API keys | Security-sensitive creation and scope selection. | Scoped creation wizard, least-privilege suggestions, clear expiry/owner explanation. |
+| User settings | Needs clarity and persistence across profile/interface/preferences. | Simple settings sections with immediate feedback and no double-click navigation traps. |
+
+## Review Checklist
+
+Every new or changed admin/configuration surface should answer:
+
+- What is the common path, and is it visible without noise?
+- Which fields are advanced, and are they collapsed by default?
+- Is every configuration value editable through typed controls?
+- Does the flow avoid JSON as the primary editor?
+- Does the screen explain disabled actions and failed validation in plain
+  language?
+- Does it say who can fix a blocker and where?
+- Does it reuse existing core patterns for wizard steps, problem lists, modals,
+  help, and review?
+- Is there a review or preflight step before broad, destructive, or risky
+  changes?
+- Does the action surface show consequence, reversibility, and audit evidence
+  when rights, duties, records, money, communication, external systems, or
+  workflow state are affected?
+- If automation is involved, can the user see the trigger, system actor,
+  observed effects, and failure/manual-intervention state?
+- Are technical details available without being the first thing the user sees?
+
+## Revision Rule
+
+When a UX decision changes:
+
+1. Update this ledger.
+2. Update the affected shared components.
+3. Update existing screens listed in the impact index.
+4. Add or update Gitea issues for any remaining surfaces that still follow the
+   old decision.
+5. Sync the wiki.

docs/audits/2026-07-09-dependency-audit.md

@@ -0,0 +1,71 @@
+# Dependency Audit - 2026-07-09
+
+Commands:
+
+```bash
+cd /mnt/DATA/git/govoplan
+GOVOPLAN_CORE_ROOT=/mnt/DATA/git/govoplan-core bash tools/checks/check-dependency-audits.sh
+```
+
+Status: remediated.
+
+Initial result:
+
+- Python audit failed: 24 advisories were reported across `cryptography`,
+  `pip`, `python-multipart`, `pyzipper`, and `starlette`.
+- npm production audit passed: `npm audit --omit=dev` reported 0
+  vulnerabilities.
+
+Python findings:
+
+| Package | Installed | Advisory count | Minimum reported fix |
+| --- | ---: | ---: | --- |
+| `cryptography` | `44.0.0` | 5 | `48.0.1` |
+| `pip` | `26.0.1` | 3 | `26.1.2` |
+| `python-multipart` | `0.0.17` | 7 | `0.0.31` |
+| `pyzipper` | `0.3.6` | 1 | `0.4.0` |
+| `starlette` | `0.41.3` | 8 | `1.3.1` |
+
+Private GovOPlaN packages were skipped by `pip-audit` because they are not
+published on PyPI. That is expected for local editable development installs.
+
+The remediation below upgrades those dependencies and records the compatibility
+checks run against core, files, and campaign behavior.
+
+## Remediation
+
+Remediation applied on 2026-07-09:
+
+- upgraded core's FastAPI floor to `fastapi>=0.139,<1`, resolving Starlette to
+  `starlette==1.3.1`
+- upgraded core's cryptography floor to `cryptography>=48.0.1,<50`, resolving
+  to `cryptography==49.0.0`
+- declared the files module upload parser dependency as
+  `python-multipart>=0.0.31,<1`, resolving to `python-multipart==0.0.32`
+- upgraded the campaign ZIP dependency to `pyzipper>=0.4,<1`, resolving to
+  `pyzipper==0.4.0`
+- upgraded the local audit environment to `pip==26.1.2`
+- removed the obsolete local `govoplan-module-multimailer` editable install
+  from the audit environment so the audit reflects the split module product
+
+Post-remediation result:
+
+- `bash tools/checks/check-dependency-audits.sh`: passed, no known Python
+  vulnerabilities found and npm production audit reported 0 vulnerabilities.
+- `python -m pip check`: passed.
+- `bash tools/checks/check-module-matrix.sh`: passed.
+- `python -m unittest tests.test_api_smoke`: passed.
+- campaign encrypted/plain ZIP smoke with `pyzipper==0.4.0`: passed.
+
+Notes:
+
+- `pip-audit` still reports private GovOPlaN packages as skipped because they
+  are not published on PyPI. That is expected for editable local development
+  installs.
+- `httpx2>=2.5,<3` is included in development requirements so Starlette's
+  `TestClient` uses the non-deprecated backend. `httpx==0.28.1` remains in dev
+  requirements for tests that mock connector HTTP responses directly.
+- Split-module API routers now use Starlette's renamed
+  `HTTP_422_UNPROCESSABLE_CONTENT` status constant. This preserves the 422
+  status code while avoiding the deprecated `HTTP_422_UNPROCESSABLE_ENTITY`
+  alias.

docs/configuration-package-catalog.example.json

@@ -0,0 +1,46 @@
+{
+  "channel": "stable",
+  "packages": [
+    {
+      "package_id": "govoplan.application-handling.basic",
+      "name": "Basic application handling",
+      "version": "0.1.0",
+      "description": "Portal form, case workflow, task creation, mail notification, payment setup, and access roles for a simple application process.",
+      "publisher": "ADD ideas",
+      "category": "workflow",
+      "artifact_ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-configuration-packages.git@application-handling-basic-v0.1.0",
+      "artifact_sha256": "<sha256>",
+      "required_modules": [
+        { "module_id": "portal", "version": ">=0.1.0" },
+        { "module_id": "forms", "version": ">=0.1.0" },
+        { "module_id": "cases", "version": ">=0.1.0" },
+        { "module_id": "workflow", "version": ">=0.1.0" },
+        { "module_id": "tasks", "version": ">=0.1.0" },
+        { "module_id": "templates", "version": ">=0.1.0" },
+        { "module_id": "mail", "version": ">=0.1.0" },
+        { "module_id": "payments", "version": ">=0.1.0" },
+        { "module_id": "access", "version": ">=0.1.0" },
+        { "module_id": "audit", "version": ">=0.1.0" }
+      ],
+      "required_capabilities": [
+        "configuration.provider",
+        "access.configuration",
+        "forms.configuration",
+        "workflow.configuration",
+        "mail.configuration",
+        "payments.configuration"
+      ],
+      "tags": ["official", "example", "public-service"],
+      "signature": {
+        "algorithm": "ed25519",
+        "key_id": "configuration-release-key-1",
+        "value": "<base64 signature over the package artifact metadata>"
+      }
+    }
+  ],
+  "signature": {
+    "algorithm": "ed25519",
+    "key_id": "configuration-catalog-key-1",
+    "value": "<base64 signature over this JSON object without the signature field>"
+  }
+}

docs/migration-release-baselines.json

@@ -0,0 +1,89 @@
+{
+  "releases": [
+    {
+      "heads": [
+        {
+          "owner": "govoplan-campaign",
+          "revision": "2c3d4e5f7081"
+        },
+        {
+          "owner": "govoplan-mail",
+          "revision": "3d4e5f708192"
+        },
+        {
+          "owner": "govoplan-idm",
+          "revision": "8f9a0b1c2d3e"
+        },
+        {
+          "owner": "govoplan-calendar",
+          "revision": "9e0f1a2b3c4d"
+        },
+        {
+          "owner": "govoplan-files",
+          "revision": "a7b8c9d0e1f3"
+        }
+      ],
+      "owner_heads": [
+        {
+          "owner": "govoplan-access",
+          "revisions": [
+            "4a5b6c7d8e9f"
+          ]
+        },
+        {
+          "owner": "govoplan-calendar",
+          "revisions": [
+            "9e0f1a2b3c4d"
+          ]
+        },
+        {
+          "owner": "govoplan-campaign",
+          "revisions": [
+            "2c3d4e5f7081"
+          ]
+        },
+        {
+          "owner": "govoplan-core",
+          "revisions": [
+            "4f2a9c8e7b6d"
+          ]
+        },
+        {
+          "owner": "govoplan-files",
+          "revisions": [
+            "a7b8c9d0e1f3"
+          ]
+        },
+        {
+          "owner": "govoplan-identity",
+          "revisions": [
+            "5c6d7e8f9a10"
+          ]
+        },
+        {
+          "owner": "govoplan-idm",
+          "revisions": [
+            "8f9a0b1c2d3e"
+          ]
+        },
+        {
+          "owner": "govoplan-mail",
+          "revisions": [
+            "3d4e5f708192"
+          ]
+        },
+        {
+          "owner": "govoplan-organizations",
+          "revisions": [
+            "6d7e8f9a0b1c"
+          ]
+        }
+      ],
+      "recorded_at": "2026-07-11T01:39:45Z",
+      "release": "0.1.7",
+      "track": "release",
+      "squash_policy": "reviewed-manual"
+    }
+  ],
+  "version": 1
+}

docs/module-package-catalog.example.json

@@ -0,0 +1,151 @@
+{
+  "catalog_version": "1",
+  "channel": "stable",
+  "sequence": 14,
+  "generated_at": "2026-07-07T00:00:00Z",
+  "expires_at": "2030-12-31T23:59:59Z",
+  "modules": [
+    {
+      "module_id": "files",
+      "name": "Files",
+      "description": "Managed file spaces and campaign attachment integration.",
+      "version": "0.1.4",
+      "action": "install",
+      "python_package": "govoplan-files",
+      "python_ref": "govoplan-files @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-files.git@v0.1.4",
+      "webui_package": "@govoplan/files-webui",
+      "webui_ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-files.git#v0.1.4",
+      "migration_safety": "forward_only",
+      "migration_notes": "Database rollback requires restoring the pre-update snapshot.",
+      "migration_after": ["access"],
+      "migration_before": ["campaigns"],
+      "migration_tasks": [
+        {
+          "task_id": "backfill_spaces",
+          "phase": "post_migration_backfill",
+          "summary": "Backfill file spaces after the schema migration.",
+          "task_version": "1",
+          "safety": "forward_only",
+          "idempotent": true,
+          "timeout_seconds": 300
+        }
+      ],
+      "current_version_min": "0.1.0",
+      "current_version_max_exclusive": "0.2.0",
+      "bridge_release": true,
+      "bridge_notes": "Keeps the 0.1.x campaign attachment interface while introducing the 0.2.x contract.",
+      "allow_downgrade": false,
+      "allow_same_version": false,
+      "recovery_tested": true,
+      "recovery_notes": "Snapshot restore and forward recovery were rehearsed on the release candidate dataset.",
+      "provides_interfaces": [
+        {
+          "name": "files.campaign_attachments",
+          "version": "1.4.0"
+        }
+      ],
+      "requires_interfaces": [
+        {
+          "name": "campaigns.access",
+          "version_min": "1.0.0",
+          "version_max_exclusive": "2.0.0",
+          "optional": true
+        }
+      ],
+      "artifact_integrity": {
+        "python": {
+          "ref": "govoplan-files @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-files.git@v0.1.4",
+          "sha256": "<sha256 of the resolved Python artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-files-0.1.4.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-files-0.1.4.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.4"
+        },
+        "webui": {
+          "ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-files.git#v0.1.4",
+          "sha256": "<sha256 of the resolved WebUI package artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-files-webui-0.1.4.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-files-webui-0.1.4.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.4"
+        }
+      },
+      "license_features": ["module.files"],
+      "tags": ["official", "service-module"]
+    },
+    {
+      "module_id": "mail",
+      "name": "Mail",
+      "description": "SMTP/IMAP profile management and read-only mailbox access.",
+      "version": "0.1.4",
+      "action": "install",
+      "python_package": "govoplan-mail",
+      "python_ref": "govoplan-mail @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-mail.git@v0.1.4",
+      "webui_package": "@govoplan/mail-webui",
+      "webui_ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-mail.git#v0.1.4",
+      "provides_interfaces": [
+        {
+          "name": "mail.campaign_delivery",
+          "version": "1.4.0"
+        }
+      ],
+      "artifact_integrity": {
+        "python": {
+          "ref": "govoplan-mail @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-mail.git@v0.1.4",
+          "sha256": "<sha256 of the resolved Python artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-mail-0.1.4.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-mail-0.1.4.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.4"
+        },
+        "webui": {
+          "ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-mail.git#v0.1.4",
+          "sha256": "<sha256 of the resolved WebUI package artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-mail-webui-0.1.4.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-mail-webui-0.1.4.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.4"
+        }
+      },
+      "license_features": ["module.mail"],
+      "tags": ["official", "service-module"]
+    },
+    {
+      "module_id": "dashboard",
+      "name": "Dashboard",
+      "description": "Configurable user home assembled from module-provided widgets.",
+      "version": "0.1.6",
+      "action": "install",
+      "python_package": "govoplan-dashboard",
+      "python_ref": "govoplan-dashboard @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-dashboard.git@v0.1.6",
+      "webui_package": "@govoplan/dashboard-webui",
+      "webui_ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-dashboard.git#v0.1.6",
+      "artifact_integrity": {
+        "python": {
+          "ref": "govoplan-dashboard @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-dashboard.git@v0.1.6",
+          "sha256": "<sha256 of the resolved Python artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-dashboard-0.1.6.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-dashboard-0.1.6.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.6"
+        },
+        "webui": {
+          "ref": "git+ssh://git@git.add-ideas.de/add-ideas/govoplan-dashboard.git#v0.1.6",
+          "sha256": "<sha256 of the resolved WebUI package artifact>",
+          "sbom_url": "https://govoplan.add-ideas.de/sbom/govoplan-dashboard-webui-0.1.6.spdx.json",
+          "provenance_url": "https://govoplan.add-ideas.de/provenance/govoplan-dashboard-webui-0.1.6.intoto.jsonl",
+          "git_ref": "refs/tags/v0.1.6"
+        }
+      },
+      "license_features": ["module.dashboard"],
+      "tags": ["official", "platform-module"]
+    }
+  ],
+  "signatures": [
+    {
+      "algorithm": "ed25519",
+      "key_id": "release-key-1",
+      "value": "<base64 signature over this JSON object without signature or signatures fields>"
+    },
+    {
+      "algorithm": "ed25519",
+      "key_id": "release-key-2",
+      "value": "<optional second signature for key rotation>"
+    }
+  ]
+}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-core"
-version = "0.1.0"
+version = "0.1.8"
 description = "Reusable GovOPlaN platform core, access, tenancy, and RBAC components."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -12,10 +12,10 @@ license = { file = "LICENSE" }
 authors = [{ name = "GovOPlaN" }]
 dependencies = [
   "SQLAlchemy>=2.0,<3",
-  "fastapi>=0.115,<1",
+  "fastapi>=0.139,<1",
   "pydantic>=2,<3",
   "pydantic-settings>=2,<3",
-  "cryptography>=44,<45",
+  "cryptography>=48.0.1,<50",
   "celery>=5,<6",
   "redis>=5,<6",
   "alembic>=1,<2",
@@ -28,15 +28,17 @@ where = ["src"]
 govoplan_core = ["py.typed"]
 
 [project.scripts]
+govoplan-config = "govoplan_core.commands.config:main"
 govoplan-devserver = "govoplan_core.devserver:main"
-
-[project.entry-points."govoplan.modules"]
-access = "govoplan_core.access.manifest:get_manifest"
+govoplan-module-install-plan = "govoplan_core.commands.module_install_plan:main"
+govoplan-module-installer = "govoplan_core.commands.module_installer:main"
 
 [project.optional-dependencies]
 server = [
+  "psycopg[binary]>=3.2,<4",
   "uvicorn[standard]>=0.32,<1",
 ]
 dev = [
   "httpx==0.28.1",
+  "httpx2>=2.5,<3",
 ]

requirements-dev.txt

@@ -1,5 +0,0 @@
--e .[server]
--e ../govoplan-files
--e ../govoplan-mail
--e ../govoplan-campaign
-httpx==0.28.1

requirements-release.txt

@@ -1,6 +0,0 @@
-# Release install from tagged module repositories.
-# Update GOVOPLAN_RELEASE_TAG together with pyproject/package versions when cutting a release.
-.[server]
-govoplan-files @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-files.git@v0.1.0
-govoplan-mail @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-mail.git@v0.1.0
-govoplan-campaign @ git+ssh://git@git.add-ideas.de/add-ideas/govoplan-campaign.git@v0.1.0

src/govoplan_core/access/__init__.py

@@ -1,2 +0,0 @@
-"""Tenant, identity, auth, RBAC, and datastore access platform module."""
-

src/govoplan_core/access/auth/__init__.py

@@ -1,2 +0,0 @@
-"""Authentication and principal helpers for platform access."""
-

src/govoplan_core/access/auth/principals.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Literal
-
-from govoplan_core.access.permissions.evaluator import scopes_grant
-
-
-AuthMethod = Literal["session", "api_key", "service_account"]
-
-
-@dataclass(frozen=True, slots=True)
-class Principal:
-    account_id: str
-    membership_id: str | None
-    tenant_id: str | None
-    scopes: frozenset[str]
-    group_ids: frozenset[str]
-    auth_method: AuthMethod
-    api_key_id: str | None = None
-    session_id: str | None = None
-    service_account_id: str | None = None
-    email: str | None = None
-    display_name: str | None = None
-
-    def has(self, required: str) -> bool:
-        return scopes_grant(self.scopes, required)
-

src/govoplan_core/access/auth/roles.py

@@ -1,82 +0,0 @@
-from __future__ import annotations
-
-from sqlalchemy.orm import Session
-
-from govoplan_core.access.db.models import Account, Group, GroupMembership, Membership, Role, RoleBinding
-from govoplan_core.access.permissions.evaluator import expand_scopes
-from govoplan_core.core.modules import PermissionDefinition, SubjectType
-
-
-def membership_group_ids(session: Session, *, tenant_id: str, membership_id: str) -> frozenset[str]:
-    rows = (
-        session.query(Group.id)
-        .join(GroupMembership, GroupMembership.group_id == Group.id)
-        .filter(
-            GroupMembership.tenant_id == tenant_id,
-            GroupMembership.membership_id == membership_id,
-            Group.is_active.is_(True),
-        )
-        .all()
-    )
-    return frozenset(row[0] for row in rows)
-
-
-def roles_for_subject(
-    session: Session,
-    *,
-    subject_type: SubjectType,
-    subject_id: str,
-    tenant_id: str | None,
-) -> list[Role]:
-    query = (
-        session.query(Role)
-        .join(RoleBinding, RoleBinding.role_id == Role.id)
-        .filter(
-            RoleBinding.subject_type == subject_type,
-            RoleBinding.subject_id == subject_id,
-        )
-    )
-    if tenant_id is None:
-        query = query.filter(RoleBinding.tenant_id.is_(None), Role.tenant_id.is_(None))
-    else:
-        query = query.filter(RoleBinding.tenant_id == tenant_id, Role.tenant_id == tenant_id)
-    return query.order_by(Role.name.asc()).all()
-
-
-def membership_roles(session: Session, membership: Membership) -> list[Role]:
-    roles_by_id = {
-        role.id: role
-        for role in roles_for_subject(
-            session,
-            subject_type="membership",
-            subject_id=membership.id,
-            tenant_id=membership.tenant_id,
-        )
-    }
-    for group_id in membership_group_ids(session, tenant_id=membership.tenant_id, membership_id=membership.id):
-        for role in roles_for_subject(session, subject_type="group", subject_id=group_id, tenant_id=membership.tenant_id):
-            roles_by_id[role.id] = role
-    return list(roles_by_id.values())
-
-
-def account_system_roles(session: Session, account: Account) -> list[Role]:
-    return roles_for_subject(session, subject_type="account", subject_id=account.id, tenant_id=None)
-
-
-def principal_scopes(
-    session: Session,
-    *,
-    account: Account,
-    membership: Membership | None,
-    include_system: bool,
-    catalog: dict[str, PermissionDefinition],
-) -> list[str]:
-    scopes: set[str] = set()
-    if membership is not None:
-        for role in membership_roles(session, membership):
-            scopes.update(role.permissions or [])
-    if include_system:
-        for role in account_system_roles(session, account):
-            scopes.update(role.permissions or [])
-    return expand_scopes(scopes, catalog=catalog)
-

src/govoplan_core/access/auth/tokens.py

@@ -1,21 +0,0 @@
-from __future__ import annotations
-
-import hashlib
-import hmac
-import secrets
-
-
-DEFAULT_RANDOM_BYTES = 32
-
-
-def generate_secret(prefix: str, *, random_bytes: int = DEFAULT_RANDOM_BYTES) -> str:
-    return prefix + secrets.token_urlsafe(random_bytes)
-
-
-def hash_secret(secret: str) -> str:
-    return hashlib.sha256(secret.encode("utf-8")).hexdigest()
-
-
-def verify_secret(secret: str, expected_hash: str) -> bool:
-    return hmac.compare_digest(hash_secret(secret), expected_hash)
-

src/govoplan_core/access/db/__init__.py

@@ -1,2 +0,0 @@
-"""Access-platform SQLAlchemy metadata and models."""
-

src/govoplan_core/access/db/base.py

@@ -1,21 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from sqlalchemy import JSON, MetaData
-from sqlalchemy.orm import DeclarativeBase
-
-from govoplan_core.db.base import NAMING_CONVENTION, TimestampMixin, utcnow
-
-
-class AccessBase(DeclarativeBase):
-    metadata = MetaData(naming_convention=NAMING_CONVENTION)
-
-    type_annotation_map = {
-        dict[str, Any]: JSON,
-        list[dict[str, Any]]: JSON,
-        list[str]: JSON,
-    }
-
-
-__all__ = ["AccessBase", "NAMING_CONVENTION", "TimestampMixin", "utcnow"]

src/govoplan_core/access/db/models.py

@@ -1,237 +0,0 @@
-from __future__ import annotations
-
-import uuid
-from datetime import datetime
-from typing import Any
-
-from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Integer, JSON, String, Text, UniqueConstraint, text
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from govoplan_core.access.db.base import AccessBase, TimestampMixin
-
-
-def new_uuid() -> str:
-    return str(uuid.uuid4())
-
-
-class Account(AccessBase, TimestampMixin):
-    __tablename__ = "access_accounts"
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    email: Mapped[str] = mapped_column(String(320), nullable=False)
-    normalized_email: Mapped[str] = mapped_column(String(320), nullable=False, unique=True, index=True)
-    display_name: Mapped[str | None] = mapped_column(String(255))
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    auth_provider: Mapped[str] = mapped_column(String(50), default="local", nullable=False)
-    password_hash: Mapped[str | None] = mapped_column(String(500))
-    password_reset_required: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    last_login_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-
-    memberships: Mapped[list[Membership]] = relationship(back_populates="account", cascade="all, delete-orphan")
-
-
-class Tenant(AccessBase, TimestampMixin):
-    __tablename__ = "access_tenants"
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    slug: Mapped[str] = mapped_column(String(100), nullable=False, unique=True, index=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text)
-    default_locale: Mapped[str] = mapped_column(String(20), default="en", nullable=False)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-
-    memberships: Mapped[list[Membership]] = relationship(back_populates="tenant", cascade="all, delete-orphan")
-
-
-class Membership(AccessBase, TimestampMixin):
-    __tablename__ = "access_memberships"
-    __table_args__ = (UniqueConstraint("tenant_id", "account_id", name="uq_access_memberships_tenant_account"),)
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=False, index=True)
-    account_id: Mapped[str] = mapped_column(ForeignKey("access_accounts.id", ondelete="CASCADE"), nullable=False, index=True)
-    email_snapshot: Mapped[str | None] = mapped_column(String(320), index=True)
-    display_name: Mapped[str | None] = mapped_column(String(255))
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-
-    account: Mapped[Account] = relationship(back_populates="memberships")
-    tenant: Mapped[Tenant] = relationship(back_populates="memberships")
-
-
-class Group(AccessBase, TimestampMixin):
-    __tablename__ = "access_groups"
-    __table_args__ = (UniqueConstraint("tenant_id", "slug", name="uq_access_groups_tenant_slug"),)
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=False, index=True)
-    slug: Mapped[str] = mapped_column(String(100), nullable=False)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text)
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    template_id: Mapped[str | None] = mapped_column(String(100), index=True)
-    is_protected: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-
-
-class GroupMembership(AccessBase, TimestampMixin):
-    __tablename__ = "access_group_memberships"
-    __table_args__ = (
-        UniqueConstraint("tenant_id", "membership_id", "group_id", name="uq_access_group_memberships_member_group"),
-    )
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=False, index=True)
-    membership_id: Mapped[str] = mapped_column(ForeignKey("access_memberships.id", ondelete="CASCADE"), nullable=False, index=True)
-    group_id: Mapped[str] = mapped_column(ForeignKey("access_groups.id", ondelete="CASCADE"), nullable=False, index=True)
-
-
-class Role(AccessBase, TimestampMixin):
-    __tablename__ = "access_roles"
-    __table_args__ = (
-        UniqueConstraint("tenant_id", "slug", name="uq_access_roles_tenant_slug"),
-        Index(
-            "uq_access_roles_system_slug",
-            "slug",
-            unique=True,
-            sqlite_where=text("tenant_id IS NULL"),
-            postgresql_where=text("tenant_id IS NULL"),
-        ),
-    )
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str | None] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=True, index=True)
-    slug: Mapped[str] = mapped_column(String(100), nullable=False)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text)
-    permissions: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
-    level: Mapped[str] = mapped_column(String(20), default="tenant", nullable=False, index=True)
-    is_builtin: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-    is_assignable: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    template_id: Mapped[str | None] = mapped_column(String(100), index=True)
-    is_protected: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-
-
-class RoleBinding(AccessBase, TimestampMixin):
-    __tablename__ = "access_role_bindings"
-    __table_args__ = (
-        Index("ix_access_role_bindings_subject", "subject_type", "subject_id"),
-        Index("ix_access_role_bindings_tenant_subject", "tenant_id", "subject_type", "subject_id"),
-    )
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str | None] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=True, index=True)
-    role_id: Mapped[str] = mapped_column(ForeignKey("access_roles.id", ondelete="CASCADE"), nullable=False, index=True)
-    subject_type: Mapped[str] = mapped_column(String(50), nullable=False)
-    subject_id: Mapped[str] = mapped_column(String(36), nullable=False)
-    created_by_account_id: Mapped[str | None] = mapped_column(String(36), index=True)
-    created_by_membership_id: Mapped[str | None] = mapped_column(String(36), index=True)
-
-
-class PermissionCatalogEntry(AccessBase, TimestampMixin):
-    __tablename__ = "access_permission_catalog"
-
-    scope: Mapped[str] = mapped_column(String(255), primary_key=True)
-    module_id: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
-    resource: Mapped[str] = mapped_column(String(100), nullable=False)
-    action: Mapped[str] = mapped_column(String(100), nullable=False)
-    label: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str] = mapped_column(Text, default="", nullable=False)
-    category: Mapped[str] = mapped_column(String(100), nullable=False)
-    level: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
-    is_deprecated: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-
-
-class RoleTemplateModel(AccessBase, TimestampMixin):
-    __tablename__ = "access_role_templates"
-    __table_args__ = (UniqueConstraint("module_id", "level", "slug", name="uq_access_role_templates_module_level_slug"),)
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    module_id: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
-    slug: Mapped[str] = mapped_column(String(100), nullable=False)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text)
-    permissions: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
-    level: Mapped[str] = mapped_column(String(20), default="tenant", nullable=False)
-    managed: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    protected: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
-
-
-class ModuleInstallation(AccessBase, TimestampMixin):
-    __tablename__ = "access_module_installations"
-
-    module_id: Mapped[str] = mapped_column(String(100), primary_key=True)
-    version: Mapped[str] = mapped_column(String(50), nullable=False)
-    enabled: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-
-
-class AuthSession(AccessBase, TimestampMixin):
-    __tablename__ = "access_auth_sessions"
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str | None] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=True, index=True)
-    membership_id: Mapped[str | None] = mapped_column(ForeignKey("access_memberships.id", ondelete="CASCADE"), nullable=True, index=True)
-    account_id: Mapped[str] = mapped_column(ForeignKey("access_accounts.id", ondelete="CASCADE"), nullable=False, index=True)
-    token_hash: Mapped[str] = mapped_column(String(255), nullable=False, unique=True, index=True)
-    csrf_token_hash: Mapped[str | None] = mapped_column(String(255))
-    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, index=True)
-    last_seen_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), index=True)
-    user_agent: Mapped[str | None] = mapped_column(String(500))
-    ip_address: Mapped[str | None] = mapped_column(String(100))
-
-
-class ApiKey(AccessBase, TimestampMixin):
-    __tablename__ = "access_api_keys"
-    __table_args__ = (Index("ix_access_api_keys_owner", "owner_subject_type", "owner_subject_id"),)
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=False, index=True)
-    owner_subject_type: Mapped[str] = mapped_column(String(50), nullable=False)
-    owner_subject_id: Mapped[str] = mapped_column(String(36), nullable=False)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    prefix: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
-    key_hash: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    scopes: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
-    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), index=True)
-
-
-class TenantDatastore(AccessBase, TimestampMixin):
-    __tablename__ = "access_tenant_datastores"
-    __table_args__ = (UniqueConstraint("tenant_id", "module_id", name="uq_access_tenant_datastores_tenant_module"),)
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=new_uuid)
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), nullable=False, index=True)
-    module_id: Mapped[str] = mapped_column(String(100), default="*", nullable=False)
-    mode: Mapped[str] = mapped_column(String(20), default="shared", nullable=False)
-    database_url_secret_ref: Mapped[str | None] = mapped_column(String(255))
-    schema_name: Mapped[str | None] = mapped_column(String(100))
-    storage_bucket: Mapped[str | None] = mapped_column(String(255))
-    region: Mapped[str | None] = mapped_column(String(100))
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-
-
-class SystemSettings(AccessBase, TimestampMixin):
-    __tablename__ = "access_system_settings"
-
-    id: Mapped[str] = mapped_column(String(36), primary_key=True, default="global")
-    default_locale: Mapped[str] = mapped_column(String(20), default="en", nullable=False)
-    allow_tenant_custom_groups: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    allow_tenant_custom_roles: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    allow_tenant_api_keys: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-
-
-class TenantSettings(AccessBase, TimestampMixin):
-    __tablename__ = "access_tenant_settings"
-
-    tenant_id: Mapped[str] = mapped_column(ForeignKey("access_tenants.id", ondelete="CASCADE"), primary_key=True)
-    allow_custom_groups: Mapped[bool | None] = mapped_column(Boolean)
-    allow_custom_roles: Mapped[bool | None] = mapped_column(Boolean)
-    allow_api_keys: Mapped[bool | None] = mapped_column(Boolean)
-    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
-

src/govoplan_core/access/db/session.py

@@ -1,22 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Generator
-
-from sqlalchemy.engine import Engine
-from sqlalchemy.orm import Session, sessionmaker
-
-from govoplan_core.db.session import create_database_engine
-
-
-def create_access_engine(database_url: str) -> Engine:
-    return create_database_engine(database_url)
-
-
-def create_access_session_factory(database_url: str) -> sessionmaker[Session]:
-    engine = create_access_engine(database_url)
-    return sessionmaker(bind=engine, autoflush=False, autocommit=False, expire_on_commit=False)
-
-
-def session_scope(session_factory: sessionmaker[Session]) -> Generator[Session, None, None]:
-    with session_factory() as session:
-        yield session

src/govoplan_core/access/manifest.py

@@ -1,119 +0,0 @@
-from __future__ import annotations
-
-from govoplan_core.access.db.base import AccessBase
-from govoplan_core.access.db import models as access_models  # noqa: F401 - populate access metadata
-from govoplan_core.core.modules import MigrationSpec, ModuleManifest, PermissionDefinition, RoleTemplate
-
-
-def _permission(scope: str, label: str, description: str, category: str, level: str) -> PermissionDefinition:
-    module_id, resource, action = scope.split(":", 2)
-    return PermissionDefinition(
-        scope=scope,
-        label=label,
-        description=description,
-        category=category,
-        level=level,  # type: ignore[arg-type]
-        module_id=module_id,
-        resource=resource,
-        action=action,
-    )
-
-
-ACCESS_PERMISSIONS: tuple[PermissionDefinition, ...] = (
-    _permission("access:tenant:read", "View tenants", "List and inspect tenant registry entries.", "Access", "system"),
-    _permission("access:tenant:create", "Create tenants", "Create tenant registry entries.", "Access", "system"),
-    _permission("access:tenant:update", "Update tenants", "Update tenant metadata and activation state.", "Access", "system"),
-    _permission("access:account:read", "View accounts", "List and inspect global login accounts.", "Access", "system"),
-    _permission("access:account:create", "Create accounts", "Create global login accounts.", "Access", "system"),
-    _permission("access:account:update", "Update accounts", "Update or suspend global login accounts.", "Access", "system"),
-    _permission("access:membership:read", "View memberships", "List tenant memberships and effective access.", "Tenant access", "tenant"),
-    _permission("access:membership:create", "Create memberships", "Create tenant-local account memberships.", "Tenant access", "tenant"),
-    _permission("access:membership:update", "Update memberships", "Update or suspend tenant memberships.", "Tenant access", "tenant"),
-    _permission("access:group:read", "View groups", "List tenant groups and members.", "Tenant access", "tenant"),
-    _permission("access:group:write", "Manage groups", "Create and update tenant groups.", "Tenant access", "tenant"),
-    _permission("access:group:manage_members", "Manage group members", "Add and remove memberships from groups.", "Tenant access", "tenant"),
-    _permission("access:role:read", "View roles", "Inspect tenant and system role definitions.", "Tenant access", "tenant"),
-    _permission("access:role:write", "Manage roles", "Create and update assignable roles.", "Tenant access", "tenant"),
-    _permission("access:role:assign", "Assign roles", "Bind roles to memberships, groups, accounts or services.", "Tenant access", "tenant"),
-    _permission("access:api_key:read", "View API keys", "List API keys without revealing secrets.", "Tenant access", "tenant"),
-    _permission("access:api_key:create", "Create API keys", "Create tenant API keys within delegation limits.", "Tenant access", "tenant"),
-    _permission("access:api_key:revoke", "Revoke API keys", "Revoke tenant API keys.", "Tenant access", "tenant"),
-    _permission("access:setting:read", "View settings", "Read access and governance settings.", "Tenant access", "tenant"),
-    _permission("access:setting:write", "Manage settings", "Update access and governance settings.", "Tenant access", "tenant"),
-    _permission("access:governance:read", "View governance", "Inspect managed role and group templates.", "Access", "system"),
-    _permission("access:governance:write", "Manage governance", "Create and assign managed role and group templates.", "Access", "system"),
-)
-
-ACCESS_ROLE_TEMPLATES: tuple[RoleTemplate, ...] = (
-    RoleTemplate(
-        slug="system_owner",
-        name="System owner",
-        description="Protected full instance-wide administration.",
-        permissions=("system:*",),
-        level="system",
-        managed=True,
-        protected=True,
-    ),
-    RoleTemplate(
-        slug="system_admin",
-        name="System administrator",
-        description="Manage tenants, accounts, settings, and governance without protected owner status.",
-        permissions=(
-            "access:tenant:read",
-            "access:tenant:create",
-            "access:tenant:update",
-            "access:account:read",
-            "access:account:create",
-            "access:account:update",
-            "access:governance:read",
-            "access:governance:write",
-        ),
-        level="system",
-        managed=True,
-        protected=False,
-    ),
-    RoleTemplate(
-        slug="tenant_owner",
-        name="Tenant owner",
-        description="Protected full tenant administration and module access.",
-        permissions=("tenant:*",),
-        level="tenant",
-        managed=True,
-        protected=True,
-    ),
-    RoleTemplate(
-        slug="access_admin",
-        name="Access administrator",
-        description="Manage memberships, groups, roles, and API keys within delegation limits.",
-        permissions=(
-            "access:membership:read",
-            "access:membership:create",
-            "access:membership:update",
-            "access:group:read",
-            "access:group:write",
-            "access:group:manage_members",
-            "access:role:read",
-            "access:role:assign",
-            "access:api_key:read",
-            "access:api_key:create",
-            "access:api_key:revoke",
-        ),
-        level="tenant",
-        managed=True,
-        protected=False,
-    ),
-)
-
-manifest = ModuleManifest(
-    id="access",
-    name="Access",
-    version="1.0.0",
-    permissions=ACCESS_PERMISSIONS,
-    role_templates=ACCESS_ROLE_TEMPLATES,
-    migration_spec=MigrationSpec(module_id="access", metadata=AccessBase.metadata),
-)
-
-
-def get_manifest() -> ModuleManifest:
-    return manifest
-

src/govoplan_core/access/permissions/__init__.py

@@ -1,2 +0,0 @@
-"""Permission definitions, evaluation, and registry helpers."""
-

src/govoplan_core/access/permissions/definitions.py

@@ -1,6 +0,0 @@
-from __future__ import annotations
-
-from govoplan_core.core.modules import PermissionDefinition, PermissionLevel, RoleTemplate
-
-__all__ = ["PermissionDefinition", "PermissionLevel", "RoleTemplate"]
-

src/govoplan_core/access/permissions/evaluator.py

@@ -1,52 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Iterable, Mapping
-
-from govoplan_core.core.modules import PermissionDefinition
-
-
-def scope_grants(granted: str, required: str, *, catalog: Mapping[str, PermissionDefinition] | None = None) -> bool:
-    if granted == required or granted == "*":
-        return True
-    if granted == "tenant:*":
-        if catalog is None:
-            return not required.startswith("system:")
-        definition = catalog.get(required)
-        return definition is not None and definition.level == "tenant"
-    if granted == "system:*":
-        if catalog is None:
-            return required.startswith("system:")
-        definition = catalog.get(required)
-        return definition is not None and definition.level == "system"
-    if granted.endswith(":*"):
-        return required.startswith(granted[:-1])
-    return False
-
-
-def scopes_grant(
-    scopes: Iterable[str],
-    required: str,
-    *,
-    catalog: Mapping[str, PermissionDefinition] | None = None,
-) -> bool:
-    return any(scope_grants(scope, required, catalog=catalog) for scope in scopes)
-
-
-def expand_scopes(
-    scopes: Iterable[str],
-    *,
-    catalog: Mapping[str, PermissionDefinition],
-    include_unknown: bool = False,
-) -> list[str]:
-    expanded: set[str] = set()
-    for scope in {str(scope) for scope in scopes if scope}:
-        matched = {candidate for candidate in catalog if scope_grants(scope, candidate, catalog=catalog)}
-        if matched:
-            expanded.update(matched)
-            if scope.endswith(":*") or scope in {"*", "tenant:*", "system:*"}:
-                expanded.add(scope)
-            continue
-        if include_unknown:
-            expanded.add(scope)
-    return sorted(expanded)
-

src/govoplan_core/access/permissions/registry.py

@@ -1,38 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Iterable
-
-from govoplan_core.access.permissions.evaluator import expand_scopes, scopes_grant
-from govoplan_core.core.modules import PermissionDefinition
-
-
-class PermissionRegistry:
-    def __init__(self, permissions: Iterable[PermissionDefinition] = ()) -> None:
-        self._catalog: dict[str, PermissionDefinition] = {}
-        for permission in permissions:
-            self.register(permission)
-
-    @property
-    def catalog(self) -> dict[str, PermissionDefinition]:
-        return dict(self._catalog)
-
-    def register(self, permission: PermissionDefinition) -> None:
-        if permission.scope in self._catalog:
-            raise ValueError(f"Duplicate permission scope: {permission.scope}")
-        self._catalog[permission.scope] = permission
-
-    def has(self, scope: str) -> bool:
-        return scope in self._catalog
-
-    def grants(self, scopes: Iterable[str], required: str) -> bool:
-        return scopes_grant(scopes, required, catalog=self._catalog)
-
-    def expand(self, scopes: Iterable[str], *, include_unknown: bool = False) -> list[str]:
-        return expand_scopes(scopes, catalog=self._catalog, include_unknown=include_unknown)
-
-    def validate_known(self, scopes: Iterable[str]) -> list[str]:
-        unknown = sorted(scope for scope in scopes if scope not in self._catalog and not scope.endswith(":*") and scope not in {"*", "tenant:*", "system:*"})
-        if unknown:
-            raise ValueError("Unknown permission scope(s): " + ", ".join(unknown))
-        return sorted(set(scopes))
-

src/govoplan_core/access/tenancy/__init__.py

@@ -1,2 +0,0 @@
-"""Tenant datastore routing abstractions."""
-

src/govoplan_core/access/tenancy/datastore.py

@@ -1,54 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Generator
-from contextlib import contextmanager
-from dataclasses import dataclass
-from typing import Literal, Protocol
-
-from sqlalchemy.orm import Session, sessionmaker
-
-
-DatastoreMode = Literal["shared", "schema", "database"]
-
-
-@dataclass(frozen=True, slots=True)
-class TenantDatastoreRef:
-    tenant_id: str
-    mode: DatastoreMode = "shared"
-    datastore_id: str | None = None
-    schema_name: str | None = None
-    database_url_secret_ref: str | None = None
-
-
-class TenantDatastore(Protocol):
-    ref: TenantDatastoreRef
-
-    @contextmanager
-    def session_for(self, module_id: str) -> Generator[Session, None, None]:
-        ...
-
-
-class DatastoreResolver(Protocol):
-    def for_tenant(self, tenant_id: str) -> TenantDatastore:
-        ...
-
-
-class SharedTenantDatastore:
-    def __init__(self, ref: TenantDatastoreRef, session_factory: sessionmaker[Session]) -> None:
-        self.ref = ref
-        self._session_factory = session_factory
-
-    @contextmanager
-    def session_for(self, module_id: str) -> Generator[Session, None, None]:
-        del module_id
-        with self._session_factory() as session:
-            yield session
-
-
-class SharedDatastoreResolver:
-    def __init__(self, session_factory: sessionmaker[Session]) -> None:
-        self._session_factory = session_factory
-
-    def for_tenant(self, tenant_id: str) -> TenantDatastore:
-        return SharedTenantDatastore(TenantDatastoreRef(tenant_id=tenant_id), self._session_factory)
-

src/govoplan_core/admin/common.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import re
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+class AdminConflictError(ValueError):
+    pass
+
+
+class AdminValidationError(ValueError):
+    pass
+
+
+def slugify(value: str) -> str:
+    slug = _SLUG_RE.sub("-", value.strip().casefold()).strip("-")
+    if not slug:
+        raise AdminValidationError("A slug must contain at least one letter or number.")
+    return slug[:100]
+

src/govoplan_core/admin/governance.py

@@ -1,313 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from sqlalchemy.orm import Session
-
-from govoplan_core.admin.service import AdminConflictError, AdminValidationError, slugify
-from govoplan_core.db.models import (
-    ApiKey,
-    GovernanceTemplate,
-    GovernanceTemplateAssignment,
-    Group,
-    GroupRoleAssignment,
-    Role,
-    SystemSettings,
-    Tenant,
-    UserGroupMembership,
-    UserRoleAssignment,
-)
-from govoplan_files.backend.db.models import FileAsset, FileFolder, FileShare
-from govoplan_core.security.permissions import validate_tenant_permissions
-
-SYSTEM_SETTINGS_ID = "global"
-TEMPLATE_KINDS = {"group", "role"}
-ASSIGNMENT_MODES = {"available", "required"}
-
-
-@dataclass(frozen=True)
-class EffectiveTenantGovernance:
-    allow_custom_groups: bool
-    allow_custom_roles: bool
-    allow_api_keys: bool
-
-
-def get_system_settings(session: Session) -> SystemSettings:
-    item = session.get(SystemSettings, SYSTEM_SETTINGS_ID)
-    if item is None:
-        item = SystemSettings(id=SYSTEM_SETTINGS_ID)
-        session.add(item)
-        session.flush()
-    return item
-
-
-def _narrowing_bool(system_allows: bool, tenant_override: bool | None) -> bool:
-    if not system_allows:
-        return False
-    return tenant_override is not False
-
-
-def effective_tenant_governance(session: Session, tenant: Tenant) -> EffectiveTenantGovernance:
-    defaults = get_system_settings(session)
-    return EffectiveTenantGovernance(
-        allow_custom_groups=_narrowing_bool(defaults.allow_tenant_custom_groups, tenant.allow_custom_groups),
-        allow_custom_roles=_narrowing_bool(defaults.allow_tenant_custom_roles, tenant.allow_custom_roles),
-        allow_api_keys=_narrowing_bool(defaults.allow_tenant_api_keys, tenant.allow_api_keys),
-    )
-
-
-def assert_tenant_governance_override_allowed(session: Session, *, field: str, value: bool | None) -> None:
-    if value is not True:
-        return
-    defaults = get_system_settings(session)
-    blocked = {
-        "allow_custom_groups": not defaults.allow_tenant_custom_groups,
-        "allow_custom_roles": not defaults.allow_tenant_custom_roles,
-        "allow_api_keys": not defaults.allow_tenant_api_keys,
-    }
-    if blocked.get(field):
-        raise AdminValidationError("Tenant governance cannot explicitly allow a capability denied by system settings.")
-
-
-def validate_template(kind: str, permissions: list[str]) -> list[str]:
-    if kind not in TEMPLATE_KINDS:
-        raise AdminValidationError("Template kind must be group or role.")
-    if kind == "group":
-        if permissions:
-            raise AdminValidationError("Group templates do not contain permissions; assign roles to groups inside each tenant.")
-        return []
-    try:
-        return validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-
-
-def create_template(
-    session: Session,
-    *,
-    kind: str,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: list[str],
-    is_active: bool,
-    assignments: list[dict[str, str]],
-) -> GovernanceTemplate:
-    normalized_slug = slugify(slug)
-    permissions = validate_template(kind, permissions)
-    exists = session.query(GovernanceTemplate).filter(
-        GovernanceTemplate.kind == kind,
-        GovernanceTemplate.slug == normalized_slug,
-    ).first()
-    if exists:
-        raise AdminConflictError(f"A {kind} template with slug {normalized_slug!r} already exists.")
-    item = GovernanceTemplate(
-        kind=kind,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description,
-        permissions=permissions,
-        is_active=is_active,
-    )
-    session.add(item)
-    session.flush()
-    set_template_assignments(session, item, assignments)
-    return item
-
-
-def update_template(
-    session: Session,
-    item: GovernanceTemplate,
-    *,
-    name: str,
-    description: str | None,
-    permissions: list[str],
-    is_active: bool,
-    assignments: list[dict[str, str]],
-) -> GovernanceTemplate:
-    item.name = name.strip()
-    item.description = description
-    item.permissions = validate_template(item.kind, permissions)
-    item.is_active = is_active
-    set_template_assignments(session, item, assignments)
-    sync_template(session, item)
-    return item
-
-
-def set_template_assignments(
-    session: Session,
-    item: GovernanceTemplate,
-    assignments: list[dict[str, str]],
-) -> None:
-    desired: dict[str, str] = {}
-    for assignment in assignments:
-        tenant_id = assignment.get("tenant_id", "")
-        mode = assignment.get("mode", "available")
-        if mode not in ASSIGNMENT_MODES:
-            raise AdminValidationError("Template assignment mode must be available or required.")
-        tenant = session.get(Tenant, tenant_id)
-        if tenant is None:
-            raise AdminValidationError(f"Unknown tenant: {tenant_id}")
-        desired[tenant_id] = mode
-
-    existing = {
-        row.tenant_id: row
-        for row in session.query(GovernanceTemplateAssignment)
-        .filter(GovernanceTemplateAssignment.template_id == item.id)
-        .all()
-    }
-    for tenant_id, row in list(existing.items()):
-        if tenant_id in desired:
-            row.mode = desired[tenant_id]
-            continue
-        _remove_materialized_template(session, item, tenant_id)
-        session.delete(row)
-
-    for tenant_id, mode in desired.items():
-        if tenant_id not in existing:
-            session.add(GovernanceTemplateAssignment(template_id=item.id, tenant_id=tenant_id, mode=mode))
-    session.flush()
-    sync_template(session, item)
-
-
-def sync_template(session: Session, item: GovernanceTemplate) -> None:
-    assignments = session.query(GovernanceTemplateAssignment).filter(
-        GovernanceTemplateAssignment.template_id == item.id
-    ).all()
-    for assignment in assignments:
-        required = assignment.mode == "required"
-        if item.kind == "group":
-            group = session.query(Group).filter(
-                Group.tenant_id == assignment.tenant_id,
-                Group.system_template_id == item.id,
-            ).first()
-            if group is None:
-                group = Group(
-                    tenant_id=assignment.tenant_id,
-                    slug=_available_slug(session, Group, assignment.tenant_id, item.slug),
-                    name=item.name,
-                    description=item.description,
-                    is_active=item.is_active,
-                    system_template_id=item.id,
-                    system_required=required,
-                )
-                session.add(group)
-            else:
-                group.name = item.name
-                group.description = item.description
-                group.system_required = required
-                if required:
-                    group.is_active = item.is_active
-        else:
-            role = session.query(Role).filter(
-                Role.tenant_id == assignment.tenant_id,
-                Role.system_template_id == item.id,
-            ).first()
-            if role is None:
-                role = Role(
-                    tenant_id=assignment.tenant_id,
-                    slug=_available_slug(session, Role, assignment.tenant_id, item.slug),
-                    name=item.name,
-                    description=item.description,
-                    permissions=item.permissions,
-                    is_builtin=False,
-                    is_assignable=item.is_active,
-                    system_template_id=item.id,
-                    system_required=required,
-                )
-                session.add(role)
-            else:
-                role.name = item.name
-                role.description = item.description
-                role.permissions = item.permissions
-                role.system_required = required
-                if required:
-                    role.is_assignable = item.is_active
-    session.flush()
-
-
-
-def delete_template(session: Session, item: GovernanceTemplate) -> None:
-    assignments = session.query(GovernanceTemplateAssignment).filter(
-        GovernanceTemplateAssignment.template_id == item.id
-    ).all()
-    for assignment in assignments:
-        _remove_materialized_template(session, item, assignment.tenant_id)
-    session.delete(item)
-
-
-def _remove_materialized_template(session: Session, item: GovernanceTemplate, tenant_id: str) -> None:
-    if item.kind == "group":
-        group = session.query(Group).filter(
-            Group.tenant_id == tenant_id,
-            Group.system_template_id == item.id,
-        ).first()
-        if group is None:
-            return
-        membership_count = session.query(UserGroupMembership).filter(UserGroupMembership.group_id == group.id).count()
-        role_count = session.query(GroupRoleAssignment).filter(GroupRoleAssignment.group_id == group.id).count()
-        owned_asset_count = session.query(FileAsset).filter(FileAsset.owner_group_id == group.id).count()
-        owned_folder_count = session.query(FileFolder).filter(FileFolder.owner_group_id == group.id).count()
-        shared_asset_count = session.query(FileShare).filter(
-            FileShare.target_type == "group", FileShare.target_id == group.id
-        ).count()
-        if membership_count or role_count or owned_asset_count or owned_folder_count or shared_asset_count:
-            raise AdminConflictError(
-                f"Cannot remove {item.name!r} from the tenant while its managed group has members, roles, files, folders or shares."
-            )
-        session.delete(group)
-        return
-
-    role = session.query(Role).filter(
-        Role.tenant_id == tenant_id,
-        Role.system_template_id == item.id,
-    ).first()
-    if role is None:
-        return
-    user_count = session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role.id).count()
-    group_count = session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role.id).count()
-    if user_count or group_count:
-        raise AdminConflictError(
-            f"Cannot remove {item.name!r} from the tenant while its managed role is assigned to users or groups."
-        )
-    session.delete(role)
-
-
-def _available_slug(session: Session, model: type[Group] | type[Role], tenant_id: str, base: str) -> str:
-    candidate = base
-    suffix = 2
-    while session.query(model).filter(model.tenant_id == tenant_id, model.slug == candidate).first():
-        candidate = f"{base}-{suffix}"
-        suffix += 1
-    return candidate
-
-
-def ensure_group_mutation_allowed(group: Group, *, requested_active: bool | None = None) -> None:
-    if group.system_template_id and group.system_required and requested_active is False:
-        raise AdminConflictError("This centrally required group cannot be deactivated by the tenant.")
-
-
-def ensure_role_mutation_allowed(role: Role, *, requested_assignable: bool | None = None) -> None:
-    if role.system_template_id:
-        if role.system_required and requested_assignable is False:
-            raise AdminConflictError("This centrally required role cannot be made unavailable by the tenant.")
-        raise AdminConflictError("Centrally managed role definitions can only be changed in System administration.")
-
-
-def assert_api_keys_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_api_keys:
-        raise AdminConflictError("API-key creation is disabled by system or tenant governance.")
-
-
-def assert_custom_groups_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_custom_groups:
-        raise AdminConflictError("Custom tenant groups are disabled by system or tenant governance.")
-
-
-def assert_custom_roles_allowed(session: Session, tenant: Tenant) -> None:
-    if not effective_tenant_governance(session, tenant).allow_custom_roles:
-        raise AdminConflictError("Custom tenant roles are disabled by system or tenant governance.")
-
-
-def active_api_key_count(session: Session, tenant_id: str) -> int:
-    return session.query(ApiKey).filter(ApiKey.tenant_id == tenant_id, ApiKey.revoked_at.is_(None)).count()

src/govoplan_core/admin/models.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import Boolean, JSON, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from govoplan_core.db.base import Base, TimestampMixin
+
+
+class SystemSettings(Base, TimestampMixin):
+    __tablename__ = "core_system_settings"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default="global")
+    default_locale: Mapped[str] = mapped_column(String(20), default="en", nullable=False)
+    allow_tenant_custom_groups: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    allow_tenant_custom_roles: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    allow_tenant_api_keys: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    settings: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict, nullable=False)
+
+
+__all__ = ["SystemSettings"]
+

src/govoplan_core/admin/service.py

@@ -1,588 +0,0 @@
-from __future__ import annotations
-
-import re
-import secrets
-import string
-from collections.abc import Iterable
-from dataclasses import dataclass
-
-from sqlalchemy import func
-from sqlalchemy.orm import Session
-
-from govoplan_core.db.models import (
-    Account,
-    ApiKey,
-    Group,
-    GroupRoleAssignment,
-    Role,
-    SystemRoleAssignment,
-    Tenant,
-    User,
-    UserGroupMembership,
-    UserRoleAssignment,
-)
-from govoplan_core.security.passwords import hash_password
-from govoplan_core.security.permissions import (
-    DEFAULT_SYSTEM_ROLES,
-    DEFAULT_TENANT_ROLES,
-    normalize_email,
-    scopes_grant,
-    validate_system_permissions,
-    validate_tenant_permissions,
-)
-
-_SLUG_RE = re.compile(r"[^a-z0-9]+")
-_TEMP_PASSWORD_ALPHABET = string.ascii_letters + string.digits + "-_!@#"
-
-
-class AdminConflictError(ValueError):
-    pass
-
-
-
-
-class AdminValidationError(ValueError):
-    pass
-
-
-@dataclass(slots=True)
-class MembershipCreationResult:
-    user: User
-    account: Account
-    temporary_password: str | None = None
-    account_created: bool = False
-
-
-def slugify(value: str) -> str:
-    slug = _SLUG_RE.sub("-", value.strip().casefold()).strip("-")
-    if not slug:
-        raise AdminValidationError("A slug must contain at least one letter or number.")
-    return slug[:100]
-
-
-def generate_temporary_password(length: int = 20) -> str:
-    return "".join(secrets.choice(_TEMP_PASSWORD_ALPHABET) for _ in range(length))
-
-
-def ensure_default_roles(session: Session, tenant: Tenant | None = None) -> dict[str, Role]:
-    definitions = DEFAULT_TENANT_ROLES if tenant is not None else DEFAULT_SYSTEM_ROLES
-    roles: dict[str, Role] = {}
-    for slug, definition in definitions.items():
-        query = session.query(Role).filter(Role.slug == slug)
-        query = query.filter(Role.tenant_id == tenant.id) if tenant is not None else query.filter(Role.tenant_id.is_(None))
-        role = query.one_or_none()
-        if role is None:
-            role = Role(
-                tenant_id=tenant.id if tenant is not None else None,
-                slug=slug,
-                name=str(definition["name"]),
-                description=str(definition.get("description") or "") or None,
-                permissions=list(definition["permissions"]),
-                is_builtin=bool(definition.get("is_builtin", True)),
-                is_assignable=bool(definition.get("is_assignable", True)),
-            )
-            session.add(role)
-            session.flush()
-        else:
-            # Tenant built-ins and explicitly managed system roles remain
-            # code-defined. Seeded, non-protected system roles are only created
-            # here and can subsequently be administered in the System roles UI.
-            managed = tenant is not None or bool(definition.get("managed", False))
-            if managed:
-                role.name = str(definition["name"])
-                role.description = str(definition.get("description") or "") or None
-                role.permissions = list(definition["permissions"])
-                role.is_builtin = bool(definition.get("is_builtin", True))
-                role.is_assignable = bool(definition.get("is_assignable", True))
-                session.add(role)
-        roles[slug] = role
-    return roles
-
-
-def get_or_create_account(
-    session: Session,
-    *,
-    email: str,
-    display_name: str | None = None,
-    password: str | None = None,
-    password_reset_required: bool = False,
-) -> tuple[Account, bool, str | None]:
-    normalized = normalize_email(email)
-    if not normalized or "@" not in normalized:
-        raise AdminValidationError("Enter a valid email address.")
-    account = session.query(Account).filter(Account.normalized_email == normalized).one_or_none()
-    if account is not None:
-        if not account.is_active:
-            raise AdminConflictError(
-                "The global account is disabled. A system administrator must reactivate it before adding a tenant membership."
-            )
-        return account, False, None
-
-    temporary_password = password or generate_temporary_password()
-    account = Account(
-        email=email.strip(),
-        normalized_email=normalized,
-        display_name=display_name.strip() if display_name else None,
-        is_active=True,
-        auth_provider="local",
-        password_hash=hash_password(temporary_password),
-        password_reset_required=password_reset_required or password is None,
-    )
-    session.add(account)
-    session.flush()
-    return account, True, temporary_password
-
-
-def create_membership(
-    session: Session,
-    *,
-    tenant: Tenant,
-    email: str,
-    display_name: str | None = None,
-    password: str | None = None,
-    password_reset_required: bool = False,
-    is_active: bool = True,
-) -> MembershipCreationResult:
-    account, account_created, temporary_password = get_or_create_account(
-        session,
-        email=email,
-        display_name=display_name,
-        password=password,
-        password_reset_required=password_reset_required,
-    )
-    existing = (
-        session.query(User)
-        .filter(User.tenant_id == tenant.id, User.account_id == account.id)
-        .one_or_none()
-    )
-    if existing is not None:
-        raise AdminConflictError("This account already belongs to the tenant.")
-
-    user = User(
-        tenant_id=tenant.id,
-        account_id=account.id,
-        email=account.email,
-        display_name=display_name.strip() if display_name else account.display_name,
-        is_active=is_active,
-        is_tenant_admin=False,
-        auth_provider=account.auth_provider,
-        password_hash=account.password_hash,
-    )
-    session.add(user)
-    session.flush()
-    return MembershipCreationResult(
-        user=user,
-        account=account,
-        temporary_password=temporary_password if account_created else None,
-        account_created=account_created,
-    )
-
-
-
-def set_user_groups(session: Session, *, user: User, group_ids: Iterable[str]) -> None:
-    ids = sorted(set(group_ids))
-    groups = (
-        session.query(Group)
-        .filter(Group.tenant_id == user.tenant_id, Group.id.in_(ids))
-        .all()
-        if ids else []
-    )
-    if len(groups) != len(ids):
-        raise AdminValidationError("One or more selected groups do not belong to the tenant.")
-
-    session.query(UserGroupMembership).filter(
-        UserGroupMembership.tenant_id == user.tenant_id,
-        UserGroupMembership.user_id == user.id,
-    ).delete(synchronize_session=False)
-    for group in groups:
-        session.add(UserGroupMembership(tenant_id=user.tenant_id, user_id=user.id, group_id=group.id))
-    session.flush()
-
-
-def set_user_roles(session: Session, *, user: User, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id == user.tenant_id, Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles are invalid or not assignable.")
-
-    session.query(UserRoleAssignment).filter(
-        UserRoleAssignment.tenant_id == user.tenant_id,
-        UserRoleAssignment.user_id == user.id,
-    ).delete(synchronize_session=False)
-    for role in roles:
-        session.add(UserRoleAssignment(tenant_id=user.tenant_id, user_id=user.id, role_id=role.id))
-    session.flush()
-
-
-def set_group_members(session: Session, *, group: Group, user_ids: Iterable[str]) -> None:
-    ids = sorted(set(user_ids))
-    users = (
-        session.query(User)
-        .filter(User.tenant_id == group.tenant_id, User.id.in_(ids))
-        .all()
-        if ids else []
-    )
-    if len(users) != len(ids):
-        raise AdminValidationError("One or more selected users do not belong to the tenant.")
-
-    session.query(UserGroupMembership).filter(
-        UserGroupMembership.tenant_id == group.tenant_id,
-        UserGroupMembership.group_id == group.id,
-    ).delete(synchronize_session=False)
-    for user in users:
-        session.add(UserGroupMembership(tenant_id=group.tenant_id, user_id=user.id, group_id=group.id))
-    session.flush()
-
-
-def set_group_roles(session: Session, *, group: Group, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id == group.tenant_id, Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles are invalid or not assignable.")
-
-    session.query(GroupRoleAssignment).filter(
-        GroupRoleAssignment.tenant_id == group.tenant_id,
-        GroupRoleAssignment.group_id == group.id,
-    ).delete(synchronize_session=False)
-    for role in roles:
-        session.add(GroupRoleAssignment(tenant_id=group.tenant_id, group_id=group.id, role_id=role.id))
-    session.flush()
-
-
-def create_custom_role(
-    session: Session,
-    *,
-    tenant: Tenant,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-) -> Role:
-    normalized_slug = slugify(slug)
-    if session.query(Role).filter(Role.tenant_id == tenant.id, Role.slug == normalized_slug).count():
-        raise AdminConflictError("A role with this slug already exists in the tenant.")
-    try:
-        validated = validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    role = Role(
-        tenant_id=tenant.id,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description.strip() if description else None,
-        permissions=validated,
-        is_builtin=False,
-        is_assignable=True,
-    )
-    session.add(role)
-    session.flush()
-    return role
-
-
-def update_custom_role(
-    session: Session,
-    *,
-    role: Role,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-    is_assignable: bool,
-) -> None:
-    if role.is_builtin:
-        raise AdminConflictError("Built-in roles are managed by the application and cannot be edited.")
-    try:
-        validated = validate_tenant_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    role.name = name.strip()
-    role.description = description.strip() if description else None
-    role.permissions = validated
-    role.is_assignable = is_assignable
-    session.add(role)
-    session.flush()
-
-
-def delete_custom_role(session: Session, role: Role) -> None:
-    if role.is_builtin:
-        raise AdminConflictError("Built-in roles cannot be deleted.")
-    assigned = session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role.id).count()
-    assigned += session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role.id).count()
-    if assigned:
-        raise AdminConflictError("Remove all user and group assignments before deleting this role.")
-    session.delete(role)
-    session.flush()
-
-
-def create_system_role(
-    session: Session,
-    *,
-    slug: str,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-) -> Role:
-    normalized_slug = slugify(slug)
-    if session.query(Role).filter(Role.tenant_id.is_(None), Role.slug == normalized_slug).count():
-        raise AdminConflictError("A system role with this slug already exists.")
-    try:
-        validated = validate_system_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    if "system:*" in validated:
-        raise AdminValidationError("Only the protected System owner role may contain system:*.")
-    role = Role(
-        tenant_id=None,
-        slug=normalized_slug,
-        name=name.strip(),
-        description=description.strip() if description else None,
-        permissions=validated,
-        is_builtin=False,
-        is_assignable=True,
-    )
-    session.add(role)
-    session.flush()
-    return role
-
-
-def update_system_role(
-    session: Session,
-    *,
-    role: Role,
-    name: str,
-    description: str | None,
-    permissions: Iterable[str],
-    is_assignable: bool,
-) -> None:
-    if role.tenant_id is not None:
-        raise AdminValidationError("This is not a system role.")
-    if role.slug == "system_owner":
-        raise AdminConflictError("The protected System owner role cannot be edited.")
-    try:
-        validated = validate_system_permissions(permissions)
-    except ValueError as exc:
-        raise AdminValidationError(str(exc)) from exc
-    if "system:*" in validated:
-        raise AdminValidationError("Only the protected System owner role may contain system:*.")
-    role.name = name.strip()
-    role.description = description.strip() if description else None
-    role.permissions = validated
-    role.is_assignable = is_assignable
-    role.is_builtin = False
-    session.add(role)
-    session.flush()
-
-
-def delete_system_role(session: Session, role: Role) -> None:
-    if role.tenant_id is not None:
-        raise AdminValidationError("This is not a system role.")
-    if role.slug == "system_owner":
-        raise AdminConflictError("The protected System owner role cannot be deleted.")
-    assigned = session.query(SystemRoleAssignment).filter(SystemRoleAssignment.role_id == role.id).count()
-    if assigned:
-        raise AdminConflictError("Remove all account assignments before deleting this system role.")
-    session.delete(role)
-    session.flush()
-
-
-def assert_can_delegate_system_permissions(actor_scopes: Iterable[str], permissions: Iterable[str]) -> None:
-    """Prevent a system administrator from defining stronger roles than they hold."""
-    from govoplan_core.security.permissions import delegateable_system_scopes
-
-    requested = set(validate_system_permissions(permissions))
-    if "system:*" in requested:
-        if not scopes_grant(actor_scopes, "system:*"):
-            raise AdminValidationError("Only a System owner may delegate full system access.")
-        return
-    allowed = delegateable_system_scopes(actor_scopes)
-    missing = sorted(scope for scope in requested if scope not in allowed)
-    if missing:
-        raise AdminValidationError("You cannot delegate system permissions you do not currently hold: " + ", ".join(missing))
-
-
-def assert_can_delegate_system_roles(
-    session: Session,
-    *,
-    actor_scopes: Iterable[str],
-    role_ids: Iterable[str],
-) -> None:
-    ids = sorted(set(role_ids))
-    if not ids:
-        return
-    roles = session.query(Role).filter(Role.tenant_id.is_(None), Role.id.in_(ids)).all()
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected system roles are invalid.")
-    for role in roles:
-        assert_can_delegate_system_permissions(actor_scopes, role.permissions or [])
-
-
-def set_system_roles(session: Session, *, account: Account, role_ids: Iterable[str]) -> None:
-    ids = sorted(set(role_ids))
-    roles = (
-        session.query(Role)
-        .filter(Role.tenant_id.is_(None), Role.id.in_(ids), Role.is_assignable.is_(True))
-        .all()
-        if ids else []
-    )
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more system roles are invalid or not assignable.")
-    for role in roles:
-        try:
-            validate_system_permissions(role.permissions or [])
-        except ValueError as exc:
-            raise AdminValidationError(str(exc)) from exc
-
-    session.query(SystemRoleAssignment).filter(SystemRoleAssignment.account_id == account.id).delete(synchronize_session=False)
-    for role in roles:
-        session.add(SystemRoleAssignment(account_id=account.id, role_id=role.id))
-    session.flush()
-    assert_system_owner_exists(session)
-
-
-def account_has_system_scope(session: Session, account: Account, required: str) -> bool:
-    roles = (
-        session.query(Role)
-        .join(SystemRoleAssignment, SystemRoleAssignment.role_id == Role.id)
-        .filter(SystemRoleAssignment.account_id == account.id, Role.tenant_id.is_(None))
-        .all()
-    )
-    return any(scopes_grant(role.permissions or [], required) for role in roles)
-
-
-def tenant_owner_user_ids(session: Session, tenant_id: str) -> set[str]:
-    """Return active tenant memberships that currently satisfy the operational-owner invariant."""
-
-    users = (
-        session.query(User)
-        .join(Account, Account.id == User.account_id)
-        .filter(
-            User.tenant_id == tenant_id,
-            User.is_active.is_(True),
-            Account.is_active.is_(True),
-        )
-        .all()
-    )
-    owner_ids: set[str] = set()
-    for user in users:
-        direct_roles = (
-            session.query(Role)
-            .join(UserRoleAssignment, UserRoleAssignment.role_id == Role.id)
-            .filter(
-                UserRoleAssignment.tenant_id == tenant_id,
-                UserRoleAssignment.user_id == user.id,
-                Role.tenant_id == tenant_id,
-            )
-            .all()
-        )
-        group_roles = (
-            session.query(Role)
-            .join(GroupRoleAssignment, GroupRoleAssignment.role_id == Role.id)
-            .join(UserGroupMembership, UserGroupMembership.group_id == GroupRoleAssignment.group_id)
-            .join(Group, Group.id == UserGroupMembership.group_id)
-            .filter(
-                UserGroupMembership.tenant_id == tenant_id,
-                UserGroupMembership.user_id == user.id,
-                Group.is_active.is_(True),
-                Role.tenant_id == tenant_id,
-            )
-            .all()
-        )
-        effective = [
-            scope
-            for role in direct_roles + group_roles
-            for scope in (role.permissions or [])
-        ]
-        if scopes_grant(effective, "admin:roles:write") and scopes_grant(effective, "campaign:send"):
-            owner_ids.add(user.id)
-    return owner_ids
-
-
-def tenant_has_owner(session: Session, tenant_id: str) -> bool:
-    return bool(tenant_owner_user_ids(session, tenant_id))
-
-
-def assert_tenant_owner_exists(session: Session, tenant_id: str) -> None:
-    session.flush()
-    tenant = session.get(Tenant, tenant_id)
-    if tenant is not None and tenant.is_active and not tenant_has_owner(session, tenant_id):
-        raise AdminConflictError("An active tenant must retain at least one active owner or administrator with full operational access.")
-
-
-def assert_system_owner_exists(session: Session) -> None:
-    """Keep one active assignment of the protected System owner role.
-
-    Other roles may hold broad system permissions, but they are intentionally
-    not substitutes for the protected break-glass owner identity.
-    """
-    session.flush()
-    owner_role = (
-        session.query(Role)
-        .filter(Role.tenant_id.is_(None), Role.slug == "system_owner")
-        .one_or_none()
-    )
-    if owner_role is None:
-        raise AdminConflictError("The protected System owner role is missing.")
-    count = (
-        session.query(func.count(SystemRoleAssignment.id))
-        .join(Account, Account.id == SystemRoleAssignment.account_id)
-        .filter(SystemRoleAssignment.role_id == owner_role.id, Account.is_active.is_(True))
-        .scalar()
-    )
-    if not count:
-        raise AdminConflictError("At least one active account must retain the protected System owner role.")
-
-
-def role_assignment_counts(session: Session, role_id: str) -> tuple[int, int]:
-    return (
-        session.query(UserRoleAssignment).filter(UserRoleAssignment.role_id == role_id).count(),
-        session.query(GroupRoleAssignment).filter(GroupRoleAssignment.role_id == role_id).count(),
-    )
-
-
-def tenant_counts(session: Session, tenant_id: str) -> dict[str, int]:
-    from govoplan_campaign.backend.db.models import Campaign
-    from govoplan_files.backend.db.models import FileAsset
-
-    return {
-        "users": session.query(User).filter(User.tenant_id == tenant_id).count(),
-        "active_users": session.query(User).filter(User.tenant_id == tenant_id, User.is_active.is_(True)).count(),
-        "groups": session.query(Group).filter(Group.tenant_id == tenant_id).count(),
-        "campaigns": session.query(Campaign).filter(Campaign.tenant_id == tenant_id).count(),
-        "files": session.query(FileAsset).filter(FileAsset.tenant_id == tenant_id).count(),
-        "api_keys": session.query(ApiKey).filter(ApiKey.tenant_id == tenant_id, ApiKey.revoked_at.is_(None)).count(),
-    }
-
-
-def assert_can_delegate_tenant_permissions(actor_scopes: Iterable[str], permissions: Iterable[str]) -> None:
-    """Prevent administrators from defining or assigning roles beyond their own effective tenant powers."""
-    from govoplan_core.security.permissions import delegateable_tenant_scopes
-    requested = set(validate_tenant_permissions(permissions))
-    if "tenant:*" in requested:
-        # Only a tenant owner-equivalent can delegate the wildcard.
-        if not scopes_grant(actor_scopes, "tenant:*"):
-            raise AdminValidationError("You cannot delegate full tenant access unless you already have it.")
-        return
-    allowed = delegateable_tenant_scopes(actor_scopes)
-    missing = sorted(scope for scope in requested if scope not in allowed)
-    if missing:
-        raise AdminValidationError("You cannot delegate permissions you do not currently hold: " + ", ".join(missing))
-
-
-def assert_can_delegate_roles(session: Session, *, actor_scopes: Iterable[str], role_ids: Iterable[str], tenant_id: str) -> None:
-    ids = sorted(set(role_ids))
-    if not ids:
-        return
-    roles = session.query(Role).filter(Role.tenant_id == tenant_id, Role.id.in_(ids)).all()
-    if len(roles) != len(ids):
-        raise AdminValidationError("One or more selected roles do not belong to the tenant.")
-    for role in roles:
-        assert_can_delegate_tenant_permissions(actor_scopes, role.permissions or [])

src/govoplan_core/admin/settings.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from govoplan_core.admin.models import SystemSettings
+
+SYSTEM_SETTINGS_ID = "global"
+
+
+def get_system_settings(session: Session) -> SystemSettings:
+    item = session.get(SystemSettings, SYSTEM_SETTINGS_ID)
+    if item is None:
+        item = SystemSettings(id=SYSTEM_SETTINGS_ID)
+        session.add(item)
+        session.flush()
+    return item

src/govoplan_core/api/v1/admin_schemas.py

@@ -1,495 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Any, Literal
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-RETENTION_DAY_KEYS = (
-    "raw_campaign_json_retention_days",
-    "generated_eml_retention_days",
-    "stored_report_detail_retention_days",
-    "mock_mailbox_retention_days",
-    "audit_detail_retention_days",
-)
-RETENTION_POLICY_FIELD_KEYS = (
-    "store_raw_campaign_json",
-    *RETENTION_DAY_KEYS,
-    "audit_detail_level",
-)
-
-
-def default_allow_lower_level_limits() -> dict[str, bool]:
-    return {key: True for key in RETENTION_POLICY_FIELD_KEYS}
-
-
-def normalize_allow_lower_level_limits(value: Any, *, fill_defaults: bool) -> dict[str, bool] | None:
-    if value in (None, ""):
-        return default_allow_lower_level_limits() if fill_defaults else None
-    if not isinstance(value, dict):
-        raise ValueError("allow_lower_level_limits must be an object")
-    normalized = default_allow_lower_level_limits() if fill_defaults else {}
-    for key, allowed in value.items():
-        clean_key = str(key)
-        if clean_key not in RETENTION_POLICY_FIELD_KEYS:
-            raise ValueError(f"Unknown retention policy field: {clean_key}")
-        normalized[clean_key] = bool(allowed)
-    return normalized
-
-
-
-class PermissionItem(BaseModel):
-    scope: str
-    label: str
-    description: str
-    category: str
-    level: Literal["tenant", "system"]
-
-
-class PermissionCatalogResponse(BaseModel):
-    permissions: list[PermissionItem]
-
-
-class AdminOverviewResponse(BaseModel):
-    active_tenant_id: str
-    active_tenant_name: str
-    tenant_count: int | None = None
-    system_account_count: int | None = None
-    system_group_template_count: int | None = None
-    system_role_template_count: int | None = None
-    user_count: int
-    active_user_count: int
-    group_count: int
-    role_count: int
-    active_api_key_count: int
-    capabilities: list[str] = Field(default_factory=list)
-
-
-class TenantAdminItem(BaseModel):
-    id: str
-    slug: str = Field(min_length=1, max_length=100)
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    default_locale: str = Field(default="en", min_length=1, max_length=20)
-    settings: dict[str, Any] = Field(default_factory=dict)
-    allow_custom_groups: bool | None = None
-    allow_custom_roles: bool | None = None
-    allow_api_keys: bool | None = None
-    effective_governance: dict[str, bool] = Field(default_factory=dict)
-    is_active: bool
-    counts: dict[str, int] = Field(default_factory=dict)
-    created_at: datetime
-    updated_at: datetime
-
-
-class TenantListResponse(BaseModel):
-    tenants: list[TenantAdminItem]
-
-
-class TenantOwnerCandidate(BaseModel):
-    account_id: str
-    email: str
-    display_name: str | None = None
-
-
-class TenantOwnerCandidateListResponse(BaseModel):
-    accounts: list[TenantOwnerCandidate]
-
-
-class TenantCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    slug: str
-    name: str
-    owner_account_id: str | None = None
-    description: str | None = None
-    default_locale: str = "en"
-    settings: dict[str, Any] = Field(default_factory=dict)
-    allow_custom_groups: bool | None = None
-    allow_custom_roles: bool | None = None
-    allow_api_keys: bool | None = None
-
-
-class TenantUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    name: str | None = Field(default=None, min_length=1, max_length=255)
-    description: str | None = None
-    default_locale: str | None = Field(default=None, min_length=1, max_length=20)
-    settings: dict[str, Any] | None = None
-    allow_custom_groups: bool | None = None
-    allow_custom_roles: bool | None = None
-    allow_api_keys: bool | None = None
-    is_active: bool | None = None
-
-
-class RoleSummary(BaseModel):
-    id: str
-    slug: str = Field(min_length=1, max_length=100)
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-    effective_permission_count: int = 0
-    is_builtin: bool = False
-    is_assignable: bool = True
-    user_assignments: int = 0
-    group_assignments: int = 0
-    level: Literal["tenant", "system"] = "tenant"
-    system_template_id: str | None = None
-    system_required: bool = False
-
-
-class GroupSummary(BaseModel):
-    id: str
-    slug: str = Field(min_length=1, max_length=100)
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    is_active: bool = True
-    member_count: int = 0
-    member_ids: list[str] = Field(default_factory=list)
-    roles: list[RoleSummary] = Field(default_factory=list)
-    created_at: datetime
-    updated_at: datetime
-    system_template_id: str | None = None
-    system_required: bool = False
-
-
-class UserAdminItem(BaseModel):
-    id: str
-    account_id: str
-    tenant_id: str
-    email: str = Field(min_length=3, max_length=320)
-    display_name: str | None = Field(default=None, max_length=255)
-    is_active: bool
-    account_is_active: bool
-    password_reset_required: bool = False
-    last_login_at: datetime | None = None
-    groups: list[GroupSummary] = Field(default_factory=list)
-    roles: list[RoleSummary] = Field(default_factory=list)
-    effective_scopes: list[str] = Field(default_factory=list)
-    is_owner: bool = False
-    is_last_active_owner: bool = False
-    created_at: datetime
-    updated_at: datetime
-
-
-class UserListResponse(BaseModel):
-    users: list[UserAdminItem]
-
-
-class UserCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    email: str
-    display_name: str | None = None
-    password: str | None = Field(default=None, min_length=10)
-    password_reset_required: bool = True
-    is_active: bool = True
-    group_ids: list[str] = Field(default_factory=list)
-    role_ids: list[str] = Field(default_factory=list)
-
-
-class UserCreateResponse(BaseModel):
-    user: UserAdminItem
-    account_created: bool
-    temporary_password: str | None = None
-
-
-class UserUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    display_name: str | None = Field(default=None, max_length=255)
-    is_active: bool | None = None
-    group_ids: list[str] | None = None
-    role_ids: list[str] | None = None
-
-
-class GroupListResponse(BaseModel):
-    groups: list[GroupSummary]
-
-
-class GroupCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    slug: str
-    name: str
-    description: str | None = None
-    is_active: bool = True
-    member_ids: list[str] = Field(default_factory=list)
-    role_ids: list[str] = Field(default_factory=list)
-
-
-class GroupUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    name: str | None = Field(default=None, min_length=1, max_length=255)
-    description: str | None = None
-    is_active: bool | None = None
-    member_ids: list[str] | None = None
-    role_ids: list[str] | None = None
-
-
-class RoleListResponse(BaseModel):
-    roles: list[RoleSummary]
-
-
-class RoleCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    slug: str
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-
-
-class RoleUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    name: str
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-    is_assignable: bool = True
-
-
-class SystemAccountItem(BaseModel):
-    account_id: str
-    email: str
-    display_name: str | None = None
-    is_active: bool
-    memberships: list[dict[str, Any]] = Field(default_factory=list)
-    roles: list[RoleSummary] = Field(default_factory=list)
-    last_login_at: datetime | None = None
-
-
-class SystemAccountListResponse(BaseModel):
-    accounts: list[SystemAccountItem]
-    roles: list[RoleSummary]
-
-
-class SystemAccountUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    display_name: str | None = Field(default=None, max_length=255)
-    is_active: bool | None = None
-    role_ids: list[str] | None = None
-
-
-class SystemAccountRolesUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    role_ids: list[str] = Field(default_factory=list)
-
-
-class SystemMembershipUpdate(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    tenant_id: str
-    is_active: bool = True
-    role_ids: list[str] = Field(default_factory=list)
-    group_ids: list[str] = Field(default_factory=list)
-
-
-class SystemAccountMembershipsUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    memberships: list[SystemMembershipUpdate] = Field(default_factory=list)
-
-
-class SystemAccountCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    email: str
-    display_name: str | None = None
-    password: str | None = Field(default=None, min_length=10)
-    password_reset_required: bool = True
-    is_active: bool = True
-    role_ids: list[str] = Field(default_factory=list)
-    memberships: list[SystemMembershipUpdate] = Field(default_factory=list)
-
-
-class SystemAccountCreateResponse(BaseModel):
-    account: SystemAccountItem
-    temporary_password: str | None = None
-
-
-class PolicySourceStepItem(BaseModel):
-    scope_type: str
-    scope_id: str | None = None
-    label: str
-    applied_fields: list[str] = Field(default_factory=list)
-
-
-class PrivacyRetentionPolicyItem(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    store_raw_campaign_json: bool = True
-    raw_campaign_json_retention_days: int | None = Field(default=None, ge=0)
-    generated_eml_retention_days: int | None = Field(default=None, ge=0)
-    stored_report_detail_retention_days: int | None = Field(default=None, ge=0)
-    mock_mailbox_retention_days: int | None = Field(default=None, ge=0)
-    audit_detail_retention_days: int | None = Field(default=None, ge=0)
-    audit_detail_level: Literal["full", "redacted", "minimal"] = "full"
-    allow_lower_level_limits: dict[str, bool] = Field(default_factory=default_allow_lower_level_limits)
-
-    @field_validator("allow_lower_level_limits", mode="before")
-    @classmethod
-    def _normalize_allow_lower_level_limits(cls, value: Any) -> Any:
-        return normalize_allow_lower_level_limits(value, fill_defaults=True)
-
-
-class PrivacyRetentionPolicyPatchItem(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    store_raw_campaign_json: bool | None = None
-    raw_campaign_json_retention_days: int | None = Field(default=None, ge=0)
-    generated_eml_retention_days: int | None = Field(default=None, ge=0)
-    stored_report_detail_retention_days: int | None = Field(default=None, ge=0)
-    mock_mailbox_retention_days: int | None = Field(default=None, ge=0)
-    audit_detail_retention_days: int | None = Field(default=None, ge=0)
-    audit_detail_level: Literal["full", "redacted", "minimal"] | None = None
-    allow_lower_level_limits: dict[str, bool] | None = None
-
-    @field_validator("allow_lower_level_limits", mode="before")
-    @classmethod
-    def _normalize_allow_lower_level_limits(cls, value: Any) -> Any:
-        return normalize_allow_lower_level_limits(value, fill_defaults=False)
-
-
-class PrivacyRetentionPolicyScopeRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    policy: PrivacyRetentionPolicyPatchItem = Field(default_factory=PrivacyRetentionPolicyPatchItem)
-
-
-class PrivacyRetentionPolicyScopeResponse(BaseModel):
-    scope_type: Literal["system", "tenant", "user", "group", "campaign"]
-    scope_id: str | None = None
-    policy: dict[str, Any]
-    effective_policy: PrivacyRetentionPolicyItem
-    parent_policy: PrivacyRetentionPolicyItem | None = None
-    effective_policy_sources: list[PolicySourceStepItem] = Field(default_factory=list)
-    parent_policy_sources: list[PolicySourceStepItem] = Field(default_factory=list)
-
-
-class RetentionRunRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    dry_run: bool = True
-
-
-class RetentionRunResponse(BaseModel):
-    result: dict[str, Any]
-
-
-class SystemSettingsItem(BaseModel):
-    default_locale: str = "en"
-    allow_tenant_custom_groups: bool = True
-    allow_tenant_custom_roles: bool = True
-    allow_tenant_api_keys: bool = True
-    privacy_retention_policy: PrivacyRetentionPolicyItem = Field(default_factory=PrivacyRetentionPolicyItem)
-    settings: dict[str, Any] = Field(default_factory=dict)
-
-
-class SystemSettingsUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    default_locale: str = Field(min_length=1, max_length=20)
-    allow_tenant_custom_groups: bool
-    allow_tenant_custom_roles: bool
-    allow_tenant_api_keys: bool
-    privacy_retention_policy: PrivacyRetentionPolicyItem | None = None
-
-
-class GovernanceAssignment(BaseModel):
-    tenant_id: str
-    mode: Literal["available", "required"] = "available"
-
-
-class GovernanceTemplateItem(BaseModel):
-    id: str
-    kind: Literal["group", "role"]
-    slug: str
-    name: str
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-    effective_permission_count: int = 0
-    is_active: bool = True
-    assignments: list[GovernanceAssignment] = Field(default_factory=list)
-    created_at: datetime
-    updated_at: datetime
-
-
-class GovernanceTemplateListResponse(BaseModel):
-    templates: list[GovernanceTemplateItem]
-
-
-class GovernanceTemplateCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    kind: Literal["group", "role"]
-    slug: str
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-    is_active: bool = True
-    assignments: list[GovernanceAssignment] = Field(default_factory=list)
-
-
-class GovernanceTemplateUpdateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    name: str = Field(min_length=1, max_length=255)
-    description: str | None = None
-    permissions: list[str] = Field(default_factory=list)
-    is_active: bool = True
-    assignments: list[GovernanceAssignment] = Field(default_factory=list)
-
-
-class ApiKeyAdminItem(BaseModel):
-    id: str
-    user_id: str
-    user_email: str
-    name: str
-    prefix: str
-    scopes: list[str] = Field(default_factory=list)
-    expires_at: datetime | None = None
-    last_used_at: datetime | None = None
-    revoked_at: datetime | None = None
-    created_at: datetime
-
-
-class ApiKeyListResponse(BaseModel):
-    api_keys: list[ApiKeyAdminItem]
-
-
-class AdminApiKeyCreateRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    name: str = Field(min_length=1, max_length=255)
-    user_id: str | None = None
-    scopes: list[str] = Field(default_factory=list)
-    expires_at: datetime | None = None
-
-
-class AdminApiKeyCreateResponse(ApiKeyAdminItem):
-    secret: str
-
-
-class AuditAdminItem(BaseModel):
-    id: str
-    scope: Literal["tenant", "system"] = "tenant"
-    tenant_id: str | None = None
-    actor_email: str | None = None
-    action: str
-    object_type: str | None = None
-    object_id: str | None = None
-    details: dict[str, Any] = Field(default_factory=dict)
-    created_at: datetime
-
-
-class AuditAdminListResponse(BaseModel):
-    items: list[AuditAdminItem]
-    total: int
-    page: int = 1
-    page_size: int = 100
-    pages: int = 1

src/govoplan_core/api/v1/audit.py

@@ -1,32 +0,0 @@
-from __future__ import annotations
-
-from fastapi import APIRouter, Depends, Query
-from sqlalchemy.orm import Session
-
-from govoplan_core.api.v1.schemas import AuditLogItemResponse, AuditLogListResponse
-from govoplan_core.auth.dependencies import ApiPrincipal, require_scope
-from govoplan_core.db.models import AuditLog
-from govoplan_core.db.session import get_session
-
-router = APIRouter(prefix="/audit", tags=["audit"])
-
-
-@router.get("", response_model=AuditLogListResponse)
-def list_audit_log(
-    limit: int = Query(default=100, ge=1, le=500),
-    offset: int = Query(default=0, ge=0),
-    action: str | None = None,
-    object_type: str | None = None,
-    object_id: str | None = None,
-    session: Session = Depends(get_session),
-    principal: ApiPrincipal = Depends(require_scope("audit:read")),
-):
-    query = session.query(AuditLog).filter(AuditLog.tenant_id == principal.tenant_id)
-    if action:
-        query = query.filter(AuditLog.action == action)
-    if object_type:
-        query = query.filter(AuditLog.object_type == object_type)
-    if object_id:
-        query = query.filter(AuditLog.object_id == object_id)
-    items = query.order_by(AuditLog.created_at.desc()).offset(offset).limit(limit).all()
-    return AuditLogListResponse(items=[AuditLogItemResponse.model_validate(item) for item in items])

src/govoplan_core/api/v1/auth.py

@@ -1,293 +0,0 @@
-from __future__ import annotations
-
-from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
-from sqlalchemy.orm import Session
-
-from govoplan_core.api.v1.schemas import (
-    GroupInfo,
-    LoginRequest,
-    LoginResponse,
-    MeResponse,
-    ProfileUpdateRequest,
-    RoleInfo,
-    SwitchTenantRequest,
-    TenantInfo,
-    TenantMembershipInfo,
-    UserInfo,
-)
-from govoplan_core.auth.dependencies import ApiPrincipal, get_api_principal
-from govoplan_core.audit.logging import audit_from_principal
-from govoplan_core.db.models import Account, Tenant, User
-from govoplan_core.db.session import get_session
-from govoplan_core.security.passwords import verify_password
-from govoplan_core.security.permissions import normalize_email
-from govoplan_core.settings import settings
-from govoplan_core.security.sessions import (
-    collect_system_roles,
-    collect_tenant_memberships,
-    collect_user_groups,
-    collect_user_roles,
-    collect_user_scopes,
-    create_auth_session,
-    switch_auth_session_tenant,
-)
-from govoplan_core.security.time import utc_now
-
-router = APIRouter(prefix="/auth", tags=["auth"])
-
-
-def _cookie_samesite() -> str:
-    value = settings.auth_cookie_samesite.lower().strip()
-    if value not in {"lax", "strict", "none"}:
-        return "lax"
-    if value == "none" and not settings.auth_cookie_secure:
-        return "lax"
-    return value
-
-
-def _set_auth_cookies(response: Response, created) -> None:
-    max_age = max(0, int((created.model.expires_at - utc_now()).total_seconds()))
-    common = {
-        "secure": settings.auth_cookie_secure,
-        "samesite": _cookie_samesite(),
-        "max_age": max_age,
-        "path": "/",
-    }
-    if settings.auth_cookie_domain:
-        common["domain"] = settings.auth_cookie_domain
-    response.set_cookie(settings.auth_session_cookie_name, created.token, httponly=True, **common)
-    response.set_cookie(settings.auth_csrf_cookie_name, created.csrf_token, httponly=False, **common)
-
-
-def _clear_auth_cookies(response: Response) -> None:
-    kwargs = {"path": "/"}
-    if settings.auth_cookie_domain:
-        kwargs["domain"] = settings.auth_cookie_domain
-    response.delete_cookie(settings.auth_session_cookie_name, **kwargs)
-    response.delete_cookie(settings.auth_csrf_cookie_name, **kwargs)
-
-
-def _tenant_info(tenant: Tenant) -> TenantInfo:
-    return TenantInfo(
-        id=tenant.id,
-        slug=tenant.slug,
-        name=tenant.name,
-        is_active=tenant.is_active,
-        default_locale=tenant.default_locale,
-    )
-
-
-def _user_info(user: User, account: Account) -> UserInfo:
-    return UserInfo(
-        id=user.id,
-        account_id=account.id,
-        email=account.email,
-        display_name=account.display_name or user.display_name,
-        tenant_display_name=user.display_name,
-        is_tenant_admin=user.is_tenant_admin,
-        password_reset_required=account.password_reset_required,
-    )
-
-
-def _roles_info(roles, *, level: str = "tenant") -> list[RoleInfo]:
-    return [
-        RoleInfo(
-            id=role.id,
-            slug=role.slug,
-            name=role.name,
-            permissions=role.permissions or [],
-            level=level,
-        )
-        for role in roles
-    ]
-
-
-def _groups_info(groups) -> list[GroupInfo]:
-    return [GroupInfo(id=group.id, slug=group.slug, name=group.name) for group in groups]
-
-
-def _tenant_memberships(session: Session, account: Account) -> list[TenantMembershipInfo]:
-    memberships: list[TenantMembershipInfo] = []
-    for user, tenant in collect_tenant_memberships(session, account):
-        roles = collect_user_roles(session, user)
-        memberships.append(
-            TenantMembershipInfo(
-                id=tenant.id,
-                slug=tenant.slug,
-                name=tenant.name,
-                is_active=tenant.is_active and user.is_active,
-                default_locale=tenant.default_locale,
-                roles=[role.slug for role in roles],
-            )
-        )
-    return memberships
-
-
-def _resolve_login_user(session: Session, payload: LoginRequest) -> tuple[Account, User, Tenant]:
-    account = (
-        session.query(Account)
-        .filter(Account.normalized_email == normalize_email(payload.email), Account.is_active.is_(True))
-        .one_or_none()
-    )
-    if account is None or not verify_password(payload.password, account.password_hash):
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid login")
-
-    query = (
-        session.query(User, Tenant)
-        .join(Tenant, Tenant.id == User.tenant_id)
-        .filter(
-            User.account_id == account.id,
-            User.is_active.is_(True),
-            Tenant.is_active.is_(True),
-        )
-    )
-    if payload.tenant_slug:
-        query = query.filter(Tenant.slug == payload.tenant_slug)
-    row = query.order_by(Tenant.name.asc()).first()
-    if row is None:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="No active tenant membership")
-    return account, row[0], row[1]
-
-
-def _me_response(
-    session: Session,
-    *,
-    account: Account,
-    user: User,
-    tenant: Tenant,
-    effective_scopes: list[str] | None = None,
-    include_system: bool = True,
-    include_all_memberships: bool = True,
-) -> MeResponse:
-    tenant_roles = collect_user_roles(session, user)
-    system_roles = collect_system_roles(session, account) if include_system else []
-    groups = collect_user_groups(session, user)
-    active_tenant = _tenant_info(tenant)
-    memberships = _tenant_memberships(session, account) if include_all_memberships else [
-        TenantMembershipInfo(
-            id=tenant.id,
-            slug=tenant.slug,
-            name=tenant.name,
-            is_active=tenant.is_active and user.is_active,
-            default_locale=tenant.default_locale,
-            roles=[role.slug for role in tenant_roles],
-        )
-    ]
-    return MeResponse(
-        user=_user_info(user, account),
-        tenant=active_tenant,
-        active_tenant=active_tenant,
-        tenants=memberships,
-        scopes=effective_scopes if effective_scopes is not None else collect_user_scopes(session, user, include_system=include_system),
-        roles=_roles_info(tenant_roles) + _roles_info(system_roles, level="system"),
-        groups=_groups_info(groups),
-    )
-
-
-@router.post("/login", response_model=LoginResponse)
-def login(payload: LoginRequest, request: Request, response: Response, session: Session = Depends(get_session)):
-    account, user, tenant = _resolve_login_user(session, payload)
-    user_agent = request.headers.get("user-agent")
-    ip_address = request.client.host if request.client else None
-    created = create_auth_session(
-        session,
-        user=user,
-        hours=settings.auth_session_hours,
-        user_agent=user_agent,
-        ip_address=ip_address,
-    )
-    me_payload = _me_response(session, account=account, user=user, tenant=tenant)
-    session.commit()
-    _set_auth_cookies(response, created)
-    return LoginResponse(
-        access_token=created.token,
-        expires_at=created.model.expires_at,
-        **me_payload.model_dump(),
-    )
-
-
-@router.get("/me", response_model=MeResponse)
-def me(principal: ApiPrincipal = Depends(get_api_principal), session: Session = Depends(get_session)):
-    tenant = session.get(Tenant, principal.tenant_id)
-    if tenant is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Active tenant not found")
-    return _me_response(
-        session,
-        account=principal.account,
-        user=principal.user,
-        tenant=tenant,
-        effective_scopes=principal.scopes,
-        include_system=principal.auth_session is not None,
-        include_all_memberships=principal.auth_session is not None,
-    )
-
-
-@router.patch("/profile", response_model=MeResponse)
-def update_profile(
-    payload: ProfileUpdateRequest,
-    principal: ApiPrincipal = Depends(get_api_principal),
-    session: Session = Depends(get_session),
-):
-    if principal.auth_session is None:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="API keys cannot edit an interactive user profile")
-
-    if "display_name" in payload.model_fields_set:
-        principal.account.display_name = payload.display_name.strip() if payload.display_name else None
-        session.add(principal.account)
-    if "tenant_display_name" in payload.model_fields_set:
-        principal.user.display_name = payload.tenant_display_name.strip() if payload.tenant_display_name else None
-        session.add(principal.user)
-
-    audit_from_principal(
-        session,
-        principal,
-        action="profile.updated",
-        object_type="account",
-        object_id=principal.account.id,
-        details={"fields": sorted(payload.model_fields_set)},
-    )
-    tenant = session.get(Tenant, principal.tenant_id)
-    if tenant is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Active tenant not found")
-    session.commit()
-    return _me_response(
-        session,
-        account=principal.account,
-        user=principal.user,
-        tenant=tenant,
-        include_system=True,
-        include_all_memberships=True,
-    )
-
-
-@router.post("/switch-tenant", response_model=MeResponse)
-def switch_tenant(
-    payload: SwitchTenantRequest,
-    principal: ApiPrincipal = Depends(get_api_principal),
-    session: Session = Depends(get_session),
-):
-    if principal.auth_session is None:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="API keys cannot switch tenant context")
-    try:
-        membership = switch_auth_session_tenant(session, principal.auth_session, payload.tenant_id)
-    except LookupError as exc:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
-    tenant = session.get(Tenant, membership.tenant_id)
-    if tenant is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tenant not found")
-    session.commit()
-    return _me_response(session, account=principal.account, user=membership, tenant=tenant)
-
-
-@router.post("/logout")
-def logout(
-    response: Response,
-    principal: ApiPrincipal = Depends(get_api_principal),
-    session: Session = Depends(get_session),
-):
-    if principal.auth_session is not None:
-        principal.auth_session.revoked_at = utc_now()
-        session.add(principal.auth_session)
-        session.commit()
-    _clear_auth_cookies(response)
-    return {"ok": True}

src/govoplan_core/api/v1/schemas.py

@@ -24,6 +24,21 @@ class AuditLogListResponse(BaseModel):
     items: list[AuditLogItemResponse]
 
 
+class DeltaDeletedItem(BaseModel):
+    id: str
+    resource_type: str | None = None
+    revision: str | None = None
+    deleted_at: datetime | None = None
+
+
+class DeltaCollectionResponse(BaseModel):
+    items: list[dict[str, Any]] = Field(default_factory=list)
+    deleted: list[DeltaDeletedItem] = Field(default_factory=list)
+    watermark: str | None = None
+    has_more: bool = False
+    full: bool = False
+
+
 class LoginRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -46,6 +61,7 @@ class TenantInfo(BaseModel):
     name: str
     is_active: bool = True
     default_locale: str = "en"
+    enabled_language_codes: list[str] = Field(default_factory=list)
 
 
 class TenantMembershipInfo(TenantInfo):
@@ -53,6 +69,16 @@ class TenantMembershipInfo(TenantInfo):
     is_active: bool = True
 
 
+class UserUiPreferences(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    compact_tables: bool = False
+    show_inline_help_hints: bool = True
+    reduce_motion: bool = False
+    sticky_section_sidebars: bool = True
+    theme: Literal["system", "light", "dark"] = "system"
+
+
 class UserInfo(BaseModel):
     id: str
     account_id: str
@@ -63,6 +89,9 @@ class UserInfo(BaseModel):
     tenant_display_name: str | None = None
     is_tenant_admin: bool = False
     password_reset_required: bool = False
+    preferred_language: str | None = None
+    enabled_language_codes: list[str] = Field(default_factory=list)
+    ui_preferences: UserUiPreferences = Field(default_factory=UserUiPreferences)
 
 
 class ProfileUpdateRequest(BaseModel):
@@ -70,6 +99,15 @@ class ProfileUpdateRequest(BaseModel):
 
     display_name: str | None = Field(default=None, max_length=255)
     tenant_display_name: str | None = Field(default=None, max_length=255)
+    preferred_language: str | None = Field(default=None, max_length=20)
+    enabled_language_codes: list[str] | None = None
+    ui_preferences: UserUiPreferences | None = None
+
+
+class LanguageInfo(BaseModel):
+    code: str
+    label: str
+    native_label: str | None = None
 
 
 class RoleInfo(BaseModel):
@@ -86,6 +124,25 @@ class GroupInfo(BaseModel):
     name: str
 
 
+class PrincipalContextInfo(BaseModel):
+    account_id: str
+    membership_id: str | None = None
+    tenant_id: str | None = None
+    identity_id: str | None = None
+    scopes: list[str] = Field(default_factory=list)
+    group_ids: list[str] = Field(default_factory=list)
+    role_ids: list[str] = Field(default_factory=list)
+    function_assignment_ids: list[str] = Field(default_factory=list)
+    delegation_ids: list[str] = Field(default_factory=list)
+    auth_method: Literal["session", "api_key", "service_account"] = "session"
+    api_key_id: str | None = None
+    session_id: str | None = None
+    service_account_id: str | None = None
+    acting_for_account_id: str | None = None
+    email: str | None = None
+    display_name: str | None = None
+
+
 class LoginResponse(BaseModel):
     access_token: str
     token_type: str = "bearer"
@@ -98,6 +155,10 @@ class LoginResponse(BaseModel):
     scopes: list[str]
     roles: list[RoleInfo] = Field(default_factory=list)
     groups: list[GroupInfo] = Field(default_factory=list)
+    principal: PrincipalContextInfo | None = None
+    available_languages: list[LanguageInfo] = Field(default_factory=list)
+    enabled_language_codes: list[str] = Field(default_factory=list)
+    default_language: str = "en"
 
 
 class MeResponse(BaseModel):
@@ -109,3 +170,7 @@ class MeResponse(BaseModel):
     scopes: list[str]
     roles: list[RoleInfo] = Field(default_factory=list)
     groups: list[GroupInfo] = Field(default_factory=list)
+    principal: PrincipalContextInfo | None = None
+    available_languages: list[LanguageInfo] = Field(default_factory=list)
+    enabled_language_codes: list[str] = Field(default_factory=list)
+    default_language: str = "en"

src/govoplan_core/api/v1/system.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from fastapi import APIRouter, Depends, HTTPException, status
-
-from govoplan_core.auth.dependencies import ApiPrincipal, require_any_scope
-
-router = APIRouter(prefix="/schemas", tags=["schemas"])
-
-
-def _load_campaign_schema() -> dict[str, Any]:
-    try:
-        from govoplan_campaign.backend.campaign.loader import load_campaign_schema
-    except ModuleNotFoundError as exc:
-        if exc.name == "govoplan_campaign" or exc.name.startswith("govoplan_campaign."):
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign module is not installed") from exc
-        raise
-    return load_campaign_schema()
-
-
-@router.get("/campaign")
-def get_campaign_schema(
-    principal: ApiPrincipal = Depends(require_any_scope("campaigns:campaign:read", "campaigns:campaign:create", "admin:roles:read")),
-) -> dict[str, Any]:
-    """Return the authoritative campaign JSON Schema used by the backend."""
-
-    del principal
-    return _load_campaign_schema()

src/govoplan_core/audit/logging.py

@@ -1,36 +1,197 @@
 from __future__ import annotations
 
+from collections.abc import Mapping
+from uuid import uuid4
 from typing import Any
 
 from sqlalchemy.orm import Session
 
-from govoplan_core.auth.dependencies import ApiPrincipal
-from govoplan_core.db.models import AuditLog
+from govoplan_core.auth import ApiPrincipal
+from govoplan_core.core.change_sequence import record_change
+from govoplan_core.core.access import AuditEvent, AuditRecordRef, AuditRecorder, CAPABILITY_AUDIT_RECORDER
+from govoplan_core.core.events import (
+    EventActorRef,
+    EventObjectRef,
+    EventTenantRef,
+    PlatformEvent,
+    current_event_trace,
+    normalize_trace_id,
+    publish_platform_event,
+)
+from govoplan_core.core.runtime import get_registry
 from govoplan_core.privacy.retention import sanitize_audit_details_for_policy
+from govoplan_core.security.redaction import redact_secret_values
 
 
-SENSITIVE_DETAIL_KEYS = {
-    "password",
-    "smtp_password",
-    "imap_password",
-    "secret",
-    "api_key",
-    "token",
+AUDIT_MODULE_ID = "audit"
+AUDIT_TENANT_EVENTS_COLLECTION = "audit.admin.tenant_events"
+AUDIT_SYSTEM_EVENTS_COLLECTION = "audit.admin.system_events"
+
+_ACTION_MODULE_PREFIXES = {
+    "api_key": "access",
+    "configuration_change": "access",
+    "configuration_package": "access",
+    "group": "access",
+    "idm": "idm",
+    "profile": "access",
+    "role": "access",
+    "system_access": "access",
+    "system_account": "access",
+    "system_memberships": "access",
+    "system_role": "access",
+    "user": "access",
+    "tenant": "tenancy",
+    "privacy_retention": "policy",
+    "retention_policy": "policy",
+    "files": "files",
+    "mail": "mail",
+    "campaign": "campaigns",
+    "report": "campaigns",
 }
 
 
+def _optional_text(value: object | None) -> str | None:
+    if value is None:
+        return None
+    candidate = str(value).strip()
+    return candidate or None
+
+
+def _compact_trace(trace: Mapping[str, object] | None) -> dict[str, str]:
+    if not isinstance(trace, Mapping):
+        return {}
+    compact: dict[str, str] = {}
+    correlation_id = _optional_text(trace.get("correlation_id"))
+    causation_id = _optional_text(trace.get("causation_id"))
+    clean_correlation_id = normalize_trace_id(correlation_id)
+    clean_causation_id = normalize_trace_id(causation_id)
+    if clean_correlation_id:
+        compact["correlation_id"] = clean_correlation_id
+    if clean_causation_id:
+        compact["causation_id"] = clean_causation_id
+    return compact
+
+
 def _sanitize_details(value: Any) -> Any:
-    if isinstance(value, dict):
-        sanitized: dict[str, Any] = {}
-        for key, item in value.items():
-            if str(key).lower() in SENSITIVE_DETAIL_KEYS:
-                sanitized[key] = "<redacted>"
-            else:
-                sanitized[key] = _sanitize_details(item)
-        return sanitized
-    if isinstance(value, list):
-        return [_sanitize_details(item) for item in value]
-    return value
+    return redact_secret_values(value)
+
+
+def audit_operation_context(
+    *,
+    module_id: object | None = None,
+    request_id: object | None = None,
+    run_id: object | None = None,
+    outcome: object | None = None,
+    trace: Mapping[str, object] | None = None,
+    **details: Any,
+) -> dict[str, Any]:
+    """Build concise operational audit details for admin and lifecycle actions."""
+
+    payload: dict[str, Any] = {}
+    for key, value in (
+        ("module_id", module_id),
+        ("request_id", request_id),
+        ("run_id", run_id),
+        ("outcome", outcome),
+    ):
+        text = _optional_text(value)
+        if text is not None:
+            payload[key] = text
+    for key, value in details.items():
+        if value is not None:
+            payload[key] = _sanitize_details(value)
+    compact_trace = _compact_trace(trace)
+    if compact_trace:
+        existing = payload.get("_trace")
+        payload["_trace"] = {**existing, **compact_trace} if isinstance(existing, dict) else compact_trace
+    return payload
+
+
+def _trace_details(
+    details: dict[str, Any],
+    *,
+    correlation_id: str | None = None,
+    causation_id: str | None = None,
+) -> tuple[dict[str, Any], dict[str, str]]:
+    active_trace = current_event_trace()
+    trace: dict[str, str] = {}
+    clean_correlation_id = normalize_trace_id(correlation_id)
+    clean_causation_id = normalize_trace_id(causation_id)
+    if clean_correlation_id or active_trace:
+        trace["correlation_id"] = clean_correlation_id or active_trace.correlation_id
+    if clean_causation_id or (active_trace and active_trace.causation_id):
+        trace["causation_id"] = clean_causation_id or str(active_trace.causation_id)
+    if not trace:
+        return details, {}
+    merged = dict(details)
+    existing = merged.get("_trace")
+    merged["_trace"] = {**existing, **trace} if isinstance(existing, dict) else trace
+    return merged, trace
+
+
+def _restore_trace_after_policy(details: dict[str, Any], trace: dict[str, str]) -> dict[str, Any]:
+    if not trace:
+        return details
+    if details.get("_trace") == trace:
+        return details
+    restored = dict(details)
+    existing = restored.get("_trace")
+    restored["_trace"] = {**existing, **trace} if isinstance(existing, dict) else trace
+    return restored
+
+
+def _module_id_for_audit_action(action: str) -> str:
+    prefix = action.split(".", 1)[0].strip().casefold()
+    return _ACTION_MODULE_PREFIXES.get(prefix, prefix or AUDIT_MODULE_ID)
+
+
+def _audit_recorder() -> AuditRecorder:
+    registry = get_registry()
+    if registry is None or not hasattr(registry, "has_capability") or not registry.has_capability(CAPABILITY_AUDIT_RECORDER):
+        return _NullAuditRecorder()
+    capability = registry.require_capability(CAPABILITY_AUDIT_RECORDER)
+    if not isinstance(capability, AuditRecorder):
+        raise RuntimeError("Audit recorder capability is invalid")
+    return capability
+
+
+class _NullAuditRecorder:
+    def record_event(self, session: object, event: AuditEvent) -> AuditRecordRef:
+        del session
+        return AuditRecordRef(
+            id=str(uuid4()),
+            scope=event.scope,
+            tenant_id=event.tenant_id,
+            user_id=event.user_id,
+            api_key_id=event.api_key_id,
+            action=event.action,
+            object_type=event.resource_type,
+            object_id=event.resource_id,
+            details=dict(event.details or {}),
+        )
+
+
+def _publish_audit_platform_event(item: AuditRecordRef) -> None:
+    trace = _compact_trace(item.details.get("_trace") if isinstance(item.details, Mapping) else None)
+    publish_platform_event(
+        PlatformEvent(
+            type=item.action,
+            module_id=_module_id_for_audit_action(item.action),
+            payload={
+                "audit_log_id": item.id,
+                "scope": item.scope,
+                "details": dict(item.details or {}),
+            },
+            correlation_id=trace.get("correlation_id"),
+            causation_id=trace.get("causation_id"),
+            actor=EventActorRef(type="user", id=item.user_id) if item.user_id else (
+                EventActorRef(type="api_key", id=item.api_key_id) if item.api_key_id else None
+            ),
+            tenant=EventTenantRef(id=item.tenant_id) if item.tenant_id else None,
+            resource=EventObjectRef(type=item.object_type, id=item.object_id) if item.object_type else None,
+            classification="internal",
+        )
+    )
 
 
 def audit_event(
@@ -44,8 +205,10 @@ def audit_event(
     object_type: str | None = None,
     object_id: str | None = None,
     details: dict[str, Any] | None = None,
+    correlation_id: str | None = None,
+    causation_id: str | None = None,
     commit: bool = False,
-) -> AuditLog:
+) -> AuditRecordRef:
     """Persist one audit event.
 
     The function deliberately accepts primitive IDs so it can be used from API
@@ -56,21 +219,42 @@ def audit_event(
     if scope not in {"tenant", "system"}:
         raise ValueError(f"Unsupported audit scope: {scope}")
 
-    item = AuditLog(
+    traced_details, trace = _trace_details(
+        _sanitize_details(details or {}),
+        correlation_id=correlation_id,
+        causation_id=causation_id,
+    )
+    stored_details = _restore_trace_after_policy(
+        sanitize_audit_details_for_policy(session, traced_details),
+        trace,
+    )
+
+    item = _audit_recorder().record_event(session, AuditEvent(
+        event_type=action,
+        action=action,
         scope=scope,
         tenant_id=tenant_id,
         user_id=user_id,
         api_key_id=api_key_id,
-        action=action,
-        object_type=object_type,
-        object_id=object_id,
-        details=sanitize_audit_details_for_policy(session, _sanitize_details(details or {})),
+        resource_type=object_type,
+        resource_id=object_id,
+        details=stored_details,
+    ))
+    record_change(
+        session,
+        module_id=AUDIT_MODULE_ID,
+        collection=AUDIT_SYSTEM_EVENTS_COLLECTION if scope == "system" else AUDIT_TENANT_EVENTS_COLLECTION,
+        resource_type="audit_log",
+        resource_id=item.id,
+        operation="created",
+        tenant_id=None if scope == "system" else tenant_id,
+        actor_type="user" if user_id else ("api_key" if api_key_id else None),
+        actor_id=user_id or api_key_id,
+        payload={"scope": scope, "action": action, "object_type": object_type, "object_id": object_id},
     )
-    session.add(item)
+    _publish_audit_platform_event(item)
     if commit:
         session.commit()
-    else:
-        session.flush()
     return item
 
 
@@ -83,8 +267,10 @@ def audit_from_principal(
     object_type: str | None = None,
     object_id: str | None = None,
     details: dict[str, Any] | None = None,
+    correlation_id: str | None = None,
+    causation_id: str | None = None,
     commit: bool = False,
-) -> AuditLog:
+) -> AuditRecordRef:
     return audit_event(
         session,
         tenant_id=principal.tenant_id,
@@ -95,5 +281,7 @@ def audit_from_principal(
         object_type=object_type,
         object_id=object_id,
         details=details,
+        correlation_id=correlation_id,
+        causation_id=causation_id,
         commit=commit,
     )

src/govoplan_core/auth/__init__.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+"""Core auth dependency facade.
+
+Routers depend on this module instead of a concrete access-provider package.
+The active auth module provides the request principal through the platform
+capability registry.
+"""
+
+from dataclasses import dataclass
+
+from fastapi import Depends, Header, HTTPException, Request, status
+from sqlalchemy.orm import Session
+
+from govoplan_core.core.access import (
+    CAPABILITY_AUTH_API_PRINCIPAL_PROVIDER,
+    ApiPrincipalProvider,
+    PermissionEvaluator,
+    PrincipalRef,
+)
+from govoplan_core.core.registry import PlatformRegistry
+from govoplan_core.db.session import get_session
+from govoplan_core.security.module_permissions import scopes_grant_compatible
+
+
+@dataclass(slots=True)
+class ApiPrincipal:
+    """Request principal exposed to API routers.
+
+    The stable fields live in ``principal``. ``account``, ``user``,
+    ``api_key``, and ``auth_session`` are provider-owned objects kept for
+    current routers that still need concrete account/session state.
+    """
+
+    principal: PrincipalRef
+    account: object
+    user: object
+    api_key: object | None = None
+    auth_session: object | None = None
+    permission_evaluator: PermissionEvaluator | None = None
+
+    @property
+    def account_id(self) -> str:
+        return self.principal.account_id
+
+    @property
+    def membership_id(self) -> str | None:
+        return self.principal.membership_id
+
+    @property
+    def tenant_id(self) -> str:
+        if self.principal.tenant_id is None:
+            raise RuntimeError("Tenant principal has no active tenant id.")
+        return self.principal.tenant_id
+
+    @property
+    def scopes(self) -> frozenset[str]:
+        return self.principal.scopes
+
+    @property
+    def group_ids(self) -> frozenset[str]:
+        return self.principal.group_ids
+
+    @property
+    def role_ids(self) -> frozenset[str]:
+        return self.principal.role_ids
+
+    @property
+    def function_assignment_ids(self) -> frozenset[str]:
+        return self.principal.function_assignment_ids
+
+    @property
+    def delegation_ids(self) -> frozenset[str]:
+        return self.principal.delegation_ids
+
+    @property
+    def identity_id(self) -> str | None:
+        return self.principal.identity_id
+
+    @property
+    def acting_for_account_id(self) -> str | None:
+        return self.principal.acting_for_account_id
+
+    @property
+    def auth_method(self) -> str:
+        return self.principal.auth_method
+
+    @property
+    def api_key_id(self) -> str | None:
+        return self.principal.api_key_id
+
+    @property
+    def session_id(self) -> str | None:
+        return self.principal.session_id
+
+    @property
+    def email(self) -> str | None:
+        return self.principal.email
+
+    @property
+    def display_name(self) -> str | None:
+        return self.principal.display_name
+
+    def has(self, required_scope: str) -> bool:
+        if self.permission_evaluator is not None:
+            return self.permission_evaluator.has_scope(self.principal, required_scope)
+        return scopes_grant_compatible(self.scopes, required_scope)
+
+    def to_platform_principal(self) -> PrincipalRef:
+        return self.principal
+
+
+def _registry_from_request(request: Request) -> PlatformRegistry | None:
+    registry = getattr(request.app.state, "govoplan_registry", None)
+    return registry if isinstance(registry, PlatformRegistry) else None
+
+
+def _api_principal_provider_from_request(request: Request) -> ApiPrincipalProvider:
+    registry = _registry_from_request(request)
+    if registry is None or not registry.has_capability(CAPABILITY_AUTH_API_PRINCIPAL_PROVIDER):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Auth provider is not available")
+    capability = registry.require_capability(CAPABILITY_AUTH_API_PRINCIPAL_PROVIDER)
+    if not isinstance(capability, ApiPrincipalProvider):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Invalid auth provider capability")
+    return capability
+
+
+def get_api_principal(
+    request: Request,
+    session: Session = Depends(get_session),
+    authorization: str | None = Header(default=None),
+    x_api_key: str | None = Header(default=None, alias="X-API-Key"),
+) -> ApiPrincipal:
+    principal = _api_principal_provider_from_request(request).resolve_api_principal(
+        request,
+        session,
+        authorization=authorization,
+        x_api_key=x_api_key,
+    )
+    if not isinstance(principal, ApiPrincipal):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Invalid API principal")
+    return principal
+
+
+def has_scope(principal: ApiPrincipal, required_scope: str) -> bool:
+    return principal.has(required_scope)
+
+
+def require_scope(required_scope: str):
+    def dependency(principal: ApiPrincipal = Depends(get_api_principal)) -> ApiPrincipal:
+        if not has_scope(principal, required_scope):
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing scope: {required_scope}")
+        return principal
+
+    return dependency
+
+
+def require_any_scope(*required_scopes: str):
+    def dependency(principal: ApiPrincipal = Depends(get_api_principal)) -> ApiPrincipal:
+        if not any(has_scope(principal, required) for required in required_scopes):
+            joined = ", ".join(required_scopes)
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Requires one of: {joined}")
+        return principal
+
+    return dependency
+
+
+__all__ = [
+    "ApiPrincipal",
+    "get_api_principal",
+    "has_scope",
+    "require_any_scope",
+    "require_scope",
+]

src/govoplan_core/auth/dependencies.py

@@ -1,223 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from fastapi import Depends, Header, HTTPException, Request, status
-from sqlalchemy.orm import Session
-
-from govoplan_core.db.models import Account, ApiKey, AuthSession, Tenant, User
-from govoplan_core.db.session import get_session
-from govoplan_core.security.module_permissions import scopes_grant_compatible
-from govoplan_core.access.auth.principals import Principal
-from govoplan_core.security.api_keys import authenticate_api_key
-from govoplan_core.security.permissions import intersect_api_key_scopes, scopes_grant
-from govoplan_core.security.sessions import authenticate_session_token, collect_user_groups, collect_user_scopes, verify_auth_session_csrf
-from govoplan_core.settings import settings
-
-
-@dataclass(slots=True)
-class ApiPrincipal:
-    """Compatibility wrapper around the platform Principal DTO.
-
-    Existing routers still expect ORM ``account`` and ``user`` objects. New
-    platform/module code should use the stable ID fields or
-    ``to_platform_principal()`` instead.
-    """
-
-    principal: Principal
-    account: Account
-    user: User
-    api_key: ApiKey | None = None
-    auth_session: AuthSession | None = None
-
-    @property
-    def account_id(self) -> str:
-        return self.principal.account_id
-
-    @property
-    def membership_id(self) -> str | None:
-        return self.principal.membership_id
-
-    @property
-    def tenant_id(self) -> str:
-        if self.principal.tenant_id is None:
-            raise RuntimeError("Tenant principal has no active tenant id.")
-        return self.principal.tenant_id
-
-    @property
-    def scopes(self) -> frozenset[str]:
-        return self.principal.scopes
-
-    @property
-    def group_ids(self) -> frozenset[str]:
-        return self.principal.group_ids
-
-    @property
-    def auth_method(self) -> str:
-        return self.principal.auth_method
-
-    @property
-    def api_key_id(self) -> str | None:
-        return self.principal.api_key_id
-
-    @property
-    def session_id(self) -> str | None:
-        return self.principal.session_id
-
-    @property
-    def email(self) -> str | None:
-        return self.principal.email
-
-    @property
-    def display_name(self) -> str | None:
-        return self.principal.display_name
-
-    def has(self, required_scope: str) -> bool:
-        # Keep legacy scope aliases alive while current routers still use the
-        # pre-platform permission catalogue.
-        return scopes_grant_compatible(self.scopes, required_scope)
-
-    def to_platform_principal(self) -> Principal:
-        return self.principal
-
-
-def _extract_token(request: Request, authorization: str | None, x_api_key: str | None) -> tuple[str | None, str]:
-    if x_api_key:
-        return x_api_key.strip(), "api_key"
-    if authorization and authorization.lower().startswith("bearer "):
-        return authorization[7:].strip(), "bearer"
-    cookie_token = request.cookies.get(settings.auth_session_cookie_name)
-    if cookie_token:
-        return cookie_token.strip(), "cookie"
-    return None, "none"
-
-
-def _requires_csrf(request: Request) -> bool:
-    return request.method.upper() not in {"GET", "HEAD", "OPTIONS", "TRACE"}
-
-
-def _principal_group_ids(session: Session, user: User) -> frozenset[str]:
-    return frozenset(group.id for group in collect_user_groups(session, user))
-
-
-def _build_api_principal(
-    session: Session,
-    *,
-    account: Account,
-    user: User,
-    tenant_id: str,
-    scopes: list[str],
-    auth_method: str,
-    api_key: ApiKey | None = None,
-    auth_session: AuthSession | None = None,
-) -> ApiPrincipal:
-    principal = Principal(
-        account_id=account.id,
-        membership_id=user.id,
-        tenant_id=tenant_id,
-        scopes=frozenset(scopes),
-        group_ids=_principal_group_ids(session, user),
-        auth_method=auth_method,  # type: ignore[arg-type]
-        api_key_id=api_key.id if api_key else None,
-        session_id=auth_session.id if auth_session else None,
-        email=account.email,
-        display_name=account.display_name or user.display_name,
-    )
-    return ApiPrincipal(
-        principal=principal,
-        account=account,
-        user=user,
-        api_key=api_key,
-        auth_session=auth_session,
-    )
-
-
-def get_api_principal(
-    request: Request,
-    session: Session = Depends(get_session),
-    authorization: str | None = Header(default=None),
-    x_api_key: str | None = Header(default=None, alias="X-API-Key"),
-) -> ApiPrincipal:
-    token, source = _extract_token(request, authorization, x_api_key)
-    if not token:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing API key or session token")
-
-    # API keys remain supported for CLI/automation. Their permissions are the
-    # intersection of the key grant and the owner's current tenant roles.
-    api_key = authenticate_api_key(session, token)
-    if api_key:
-        user = session.get(User, api_key.user_id)
-        account = session.get(Account, user.account_id) if user else None
-        tenant = session.get(Tenant, api_key.tenant_id)
-        if (
-            not user or not account or not tenant
-            or not user.is_active or not account.is_active or not tenant.is_active
-            or user.tenant_id != api_key.tenant_id
-        ):
-            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Inactive or inconsistent API-key principal")
-        user_scopes = collect_user_scopes(session, user, include_system=False)
-        effective_scopes = intersect_api_key_scopes(user_scopes, api_key.scopes or [])
-        session.commit()
-        return _build_api_principal(
-            session,
-            api_key=api_key,
-            account=account,
-            user=user,
-            tenant_id=api_key.tenant_id,
-            scopes=effective_scopes,
-            auth_method="api_key",
-        )
-
-    auth_session = authenticate_session_token(session, token)
-    if auth_session:
-        user = session.get(User, auth_session.user_id)
-        account = session.get(Account, auth_session.account_id)
-        tenant = session.get(Tenant, auth_session.tenant_id)
-        if (
-            not user or not account or not tenant
-            or not user.is_active or not account.is_active or not tenant.is_active
-            or user.account_id != account.id
-            or user.tenant_id != tenant.id
-        ):
-            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Inactive or inconsistent session principal")
-        if source == "cookie" and _requires_csrf(request):
-            header_token = request.headers.get("x-csrf-token")
-            cookie_token = request.cookies.get(settings.auth_csrf_cookie_name)
-            if not header_token or not cookie_token or header_token != cookie_token or not verify_auth_session_csrf(auth_session, header_token):
-                raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Invalid or missing CSRF token")
-        scopes = collect_user_scopes(session, user, include_system=True)
-        session.commit()
-        return _build_api_principal(
-            session,
-            auth_session=auth_session,
-            account=account,
-            user=user,
-            tenant_id=user.tenant_id,
-            scopes=scopes,
-            auth_method="session",
-        )
-
-    raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API key or session token")
-
-
-def has_scope(principal: ApiPrincipal, required_scope: str) -> bool:
-    return principal.has(required_scope)
-
-
-def require_scope(required_scope: str):
-    def dependency(principal: ApiPrincipal = Depends(get_api_principal)) -> ApiPrincipal:
-        if not has_scope(principal, required_scope):
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing scope: {required_scope}")
-        return principal
-
-    return dependency
-
-
-def require_any_scope(*required_scopes: str):
-    def dependency(principal: ApiPrincipal = Depends(get_api_principal)) -> ApiPrincipal:
-        if not any(has_scope(principal, required) for required in required_scopes):
-            joined = ", ".join(required_scopes)
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Requires one of: {joined}")
-        return principal
-
-    return dependency

src/govoplan_core/celery_app.py

@@ -2,8 +2,13 @@ from __future__ import annotations
 
 from celery import Celery
 
+from govoplan_core.core.campaigns import CAPABILITY_CAMPAIGNS_DELIVERY_TASKS, CampaignDeliveryTaskProvider
+from govoplan_core.core.module_management import load_startup_enabled_modules, startup_candidate_module_ids
+from govoplan_core.core.modules import ModuleContext
+from govoplan_core.core.runtime import configure_runtime
 from govoplan_core.settings import settings
 from govoplan_core.db.session import configure_database
+from govoplan_core.server.registry import available_module_manifests, build_platform_registry
 
 configure_database(settings.database_url)
 
@@ -30,6 +35,21 @@ def ping():
     return "pong"
 
 
+def _campaign_delivery_tasks() -> CampaignDeliveryTaskProvider:
+    raw_enabled_modules = load_startup_enabled_modules(settings.enabled_modules)
+    candidate_modules = startup_candidate_module_ids(settings.enabled_modules, raw_enabled_modules)
+    available_modules = available_module_manifests(enabled_modules=candidate_modules, ignore_load_errors=True)
+    enabled_modules = load_startup_enabled_modules(settings.enabled_modules, available=available_modules)
+    registry = build_platform_registry(enabled_modules)
+    context = ModuleContext(registry=registry, settings=settings)
+    configure_runtime(context)
+    registry.configure_capability_context(context)
+    capability = registry.require_capability(CAPABILITY_CAMPAIGNS_DELIVERY_TASKS)
+    if not isinstance(capability, CampaignDeliveryTaskProvider):
+        raise RuntimeError("Campaign delivery task capability is invalid")
+    return capability
+
+
 @celery.task(name="multimailer.send_email", bind=True, max_retries=0)
 def send_email(self, job_id: str):
     """Send one explicitly queued campaign job.
@@ -40,10 +60,9 @@ def send_email(self, job_id: str):
     """
 
     from govoplan_core.db.session import get_database
-    from govoplan_campaign.backend.sending.jobs import send_campaign_job
 
     with get_database().SessionLocal() as session:
-        return send_campaign_job(session, job_id=job_id, enqueue_imap_task=True).as_dict()
+        return dict(_campaign_delivery_tasks().send_campaign_job(session, job_id=job_id, enqueue_imap_task=True))
 
 
 @celery.task(name="multimailer.append_sent", bind=True, max_retries=None)
@@ -51,13 +70,11 @@ def append_sent(self, job_id: str):
     """Append the exact sent MIME to the configured IMAP Sent folder."""
 
     from govoplan_core.db.session import get_database
-    from govoplan_mail.backend.sending.imap import ImapAppendError
-    from govoplan_campaign.backend.sending.jobs import append_sent_for_job
 
     with get_database().SessionLocal() as session:
         try:
-            return append_sent_for_job(session, job_id=job_id).as_dict()
-        except ImapAppendError as exc:
+            return dict(_campaign_delivery_tasks().append_sent_for_job(session, job_id=job_id))
+        except Exception as exc:
             if getattr(exc, "temporary", None) is True:
                 raise self.retry(exc=exc, countdown=300)
             raise

src/govoplan_core/commands/config.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from govoplan_core.core.install_config import env_template, validate_runtime_configuration
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate and validate GovOPlaN install/runtime configuration.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    env_parser = subparsers.add_parser("env-template", help="Print or write an install .env template.")
+    env_parser.add_argument("--profile", default="self-hosted", choices=("self-hosted", "production-like"), help="Template profile to generate.")
+    env_parser.add_argument("--output", type=Path, help="Write the template to this path instead of stdout.")
+    env_parser.add_argument("--overwrite", action="store_true", help="Overwrite an existing output path.")
+    env_parser.add_argument("--generate-secrets", action="store_true", help="Generate a fresh MASTER_KEY_B64 in the template.")
+
+    validate_parser = subparsers.add_parser("validate", help="Validate the current process environment.")
+    validate_parser.add_argument("--profile", help="Install profile. Defaults to GOVOPLAN_INSTALL_PROFILE or APP_ENV.")
+    validate_parser.add_argument("--strict", action="store_true", help="Treat warnings as errors.")
+    validate_parser.add_argument("--format", choices=("text", "json"), default="text", help="Output format.")
+
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parse_args(argv)
+    if args.command == "env-template":
+        payload = env_template(profile=args.profile, generate_secrets=args.generate_secrets)
+        if args.output is None:
+            print(payload, end="")
+            return 0
+        output = args.output.expanduser()
+        if output.exists() and not args.overwrite:
+            print(f"Refusing to overwrite existing file: {output}", file=sys.stderr)
+            return 2
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload, encoding="utf-8")
+        print(f"Wrote {output}")
+        return 0
+
+    if args.command == "validate":
+        result = validate_runtime_configuration(profile=args.profile, strict=args.strict)
+        print(result.to_json() if args.format == "json" else result.to_text())
+        return 0 if result.ok else 1
+
+    raise AssertionError(f"Unhandled command: {args.command}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/govoplan_core/commands/init_db.py

@@ -1,21 +1,68 @@
 from __future__ import annotations
 
 import argparse
+import json
+from pathlib import Path
 
 from govoplan_core.db.bootstrap import bootstrap_dev_data
-from govoplan_core.db.migrations import migrate_database
+from govoplan_core.db.migrations import (
+    ModuleMigrationTaskExecutionError,
+    POST_MIGRATION_TASK_PHASES,
+    PRE_MIGRATION_TASK_PHASES,
+    migrate_database,
+    run_registered_module_migration_tasks,
+)
 from govoplan_core.db.session import configure_database, get_database
 from govoplan_core.settings import settings
 
 
 def main() -> None:
     parser = argparse.ArgumentParser(description="Initialize the GovOPlaN database")
+    parser.add_argument("--database-url", default=settings.database_url, help="Database URL to migrate")
+    parser.add_argument(
+        "--migration-track",
+        default=settings.migration_track,
+        choices=("release", "dev"),
+        help="Alembic migration track to load: release uses squashed release shortcuts; dev uses detailed development chains.",
+    )
+    parser.add_argument("--enabled-module", action="append", default=[], help="Target enabled module id used to discover module migrations; may be repeated.")
+    parser.add_argument("--migration-module", action="append", default=[], help="Module id whose migration heads should be upgraded in this order before final heads.")
+    parser.add_argument("--migration-task-record-output", type=Path, help="Write executed module migration task records to this JSON file.")
     parser.add_argument("--with-dev-data", action="store_true", help="Create default tenant/user/roles and a development API key")
     parser.add_argument("--dev-api-key", default=settings.dev_bootstrap_api_key, help="Development API key secret to create")
     args = parser.parse_args()
 
-    configure_database(settings.database_url)
-    migration = migrate_database()
+    configure_database(args.database_url)
+    enabled_modules = tuple(args.enabled_module) if args.enabled_module else None
+    migration_order = tuple(args.migration_module) if args.migration_module else None
+    task_records: list[dict[str, object]] = []
+    try:
+        _run_migration_tasks(
+            task_records,
+            database_url=args.database_url,
+            enabled_modules=enabled_modules,
+            migration_order=migration_order,
+            phases=PRE_MIGRATION_TASK_PHASES,
+        )
+        migration = migrate_database(
+            database_url=args.database_url,
+            enabled_modules=enabled_modules,
+            migration_module_order=migration_order,
+            migration_track=args.migration_track,
+        )
+        _run_migration_tasks(
+            task_records,
+            database_url=args.database_url,
+            enabled_modules=enabled_modules,
+            migration_order=migration_order,
+            phases=POST_MIGRATION_TASK_PHASES,
+        )
+    finally:
+        if args.migration_task_record_output:
+            args.migration_task_record_output.parent.mkdir(parents=True, exist_ok=True)
+            args.migration_task_record_output.write_text(json.dumps(task_records, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    if task_records:
+        print(f"Executed {len(task_records)} module migration task(s).")
     if migration.reconciled_revision:
         print(f"Reconciled legacy database marker to {migration.reconciled_revision}.")
     print(f"Database schema upgraded to {migration.current_revision}.")
@@ -32,5 +79,26 @@ def main() -> None:
                 print("Development API key already exists or was not requested.")
 
 
+def _run_migration_tasks(
+    target: list[dict[str, object]],
+    *,
+    database_url: str,
+    enabled_modules: tuple[str, ...] | None,
+    migration_order: tuple[str, ...] | None,
+    phases: tuple[str, ...],
+) -> None:
+    try:
+        records = run_registered_module_migration_tasks(
+            database_url=database_url,
+            enabled_modules=enabled_modules,
+            migration_module_order=migration_order,
+            phases=phases,
+        )
+    except ModuleMigrationTaskExecutionError as exc:
+        target.extend(exc.records)
+        raise
+    target.extend(records)
+
+
 if __name__ == "__main__":
     main()