govoplan/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md

# GovOPlaN Capability and IT-Infrastructure Fit Assessment

## Assessment record

| Field | Value |
| --- | --- |
| Assessment ID | `campaign-reference-2026-07-22` |
| Schema | `govoplan.fit-assessment/0.1.0` |
| Assessed on | 2026-07-22 |
| Product snapshot | Live Ed25519-signed stable catalog sequence `202607220843`: Core `v0.1.13` and Campaign `v0.1.10` |
| Configuration basis | Root `.env.example` and the production-like development profile |
| Scope | Campaign-centric internal pilot and small-production candidate |
| Explicitly postponed | Workflow and workflow-driven user stories |
| Machine-readable companion | [`capability-fit-current.json`](capability-fit-current.json) |
| Input schema | [`capability-fit.schema.json`](capability-fit.schema.json) |

This is a fit assessment, not a production approval or security certification.
It deliberately does not infer implementation from a repository, issue, or
manifest existing. A conclusion needs code plus a route/contract, test,
operational drill, configured example, or explicit evidence that the capability
is absent.

The release baseline below is reproducible at its tagged source and package
references. Later main-branch commits do not become release capabilities merely
because they are committed, pushed, or code-tested. This assessment therefore
distinguishes code-tested, package-integrated, target-tested, and
production-approved evidence explicitly.

## Controlled status vocabulary

| Status | Meaning |
| --- | --- |
| `verified` | The stated capability is implemented and directly exercised by evidence appropriate to the stated scope. Conditions and target-environment proof may still remain. |
| `available_unconfigured` | An implementation and supporting evidence exist, but the target endpoint, credentials, policy, or deployment component has not been configured and exercised. |
| `partial` | A useful subset exists, but one or more material parts of the stated journey or operational requirement are missing or unproved. |
| `scaffold` | Contracts, models, routes, or UI structure exist, but the end-to-end capability is not yet usable. |
| `external_system` | GovOPlaN expects the deployment or another system to supply this capability; integration requirements must still be assessed. |
| `planned` | The capability is represented only by a concept, backlog item, or design direction. |
| `not_fit` | Evidence shows that the current composition cannot meet the stated requirement. |
| `not_assessed` | The requirement or target environment is not sufficiently known to reach a conclusion. |

Status alone is not enough. Every row also states its evidence scope and
conditions. For example, a unit-tested SMTP adapter is
`available_unconfigured`, not `verified` for an organization's mail system.

## Executive conclusion

GovOPlaN is a credible candidate for a controlled, Campaign-centric internal
pilot using local accounts, PostgreSQL, durable single-node file storage, and a
non-production SMTP/IMAP service. The module contract, Campaign authoring and
validation paths, managed attachments, mail-profile boundary, local audit
records, and operator status surface all have direct code/test evidence.

The signed catalog resolves the earlier source/package reproducibility gap, but
it does not make the composition production-approved. The production-like
profile intentionally runs only PostgreSQL and Redis in containers; API,
WebUI, worker, and scheduler processes still run from editable source trees. A
target deployment must supply TLS termination, process supervision, secret
injection, monitoring, backup storage, and recovery procedures. The open
[Core backup/restore issue #29](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/29)
is a production gate. Identity federation, external audit export, and a tested
disaster-recovery plan are also not complete.

The current recommendation is therefore:

- **Pilot:** fit with conditions and a bounded proof of concept.
- **Small production:** partial fit; do not approve until the proof checks and
  operational gates below pass against the signed release and target
  environment.
- **Workflow:** planned and postponed; it is not part of either recommended
  composition in this assessment.

## Pinned composition

The configured reference composition comes from the meta repository's
`ENABLED_MODULES`. Versions and refs below are pinned by the live stable catalog;
commits are the commits peeled from those annotated tags.

| Module | Tagged source commit | Catalog version/ref | Role in this assessment |
| --- | --- | --- | --- |
| Core runtime | `govoplan-core@d487726f4d2c` | `0.1.13` / `v0.1.13` | API, registry, migration orchestration, shared WebUI, sessions and kernel contracts |
| `tenancy` | `govoplan-tenancy@efbec827616b` | `0.1.8` / `v0.1.8` | tenant context and lifecycle |
| `organizations` | `govoplan-organizations@39c081c4fb8f` | `0.1.8` / `v0.1.8` | organization model |
| `identity` | `govoplan-identity@7a1710af896f` | `0.1.8` / `v0.1.8` | normalized internal identity directory |
| `access` | `govoplan-access@f1d64d247e12` | `0.1.11` / `v0.1.11` | local authentication, sessions, API keys and RBAC |
| `admin` | `govoplan-admin@11ecf362a36d` | `0.1.8` / `v0.1.8` | administration surfaces |
| `dashboard` | `govoplan-dashboard@4b960ad37f0d` | `0.1.8` / `v0.1.8` | module-aware home surface |
| `policy` | `govoplan-policy@1063622d311a` | `0.1.9` / `v0.1.9` | policy explanation/configuration boundary |
| `audit` | `govoplan-audit@d3d2c60d7dc1` | `0.1.8` / `v0.1.8` | database audit records and retrying audit outbox |
| `campaigns` | `govoplan-campaign@735e874bd03c` | `0.1.10` / `v0.1.10` | Campaign authoring, build, delivery control and reporting |
| `files` | `govoplan-files@2b34f6e30578` | `0.1.9` / `v0.1.9` | managed files and Campaign attachments |
| `mail` | `govoplan-mail@3e2302909022` | `0.1.10` / `v0.1.10` | SMTP/IMAP profiles and transports |
| `calendar` | `govoplan-calendar@9bcf41bb1fbb` | `0.1.8` / `v0.1.8` | optional calendar; not needed by the Campaign pilot |
| `docs` | `govoplan-docs@be52b716caed` | `0.1.10` / `v0.1.10` | configured-system documentation |
| `ops` | `govoplan-ops@341773a4ff8a` | `0.1.8` / `v0.1.8` | readiness and deployment-profile visibility |

Stable catalog sequence `202607220843` is valid, signed by trusted key
`release-key-1`, and pins matching Python and WebUI refs where applicable. This
proves release source/package selection and provenance, not behavior in a target
environment. No configuration revision/package is pinned yet, so deployment
configuration remains a separate reproducibility and promotion gate. The static
contract scan found 43 interface contracts, 33 providers, and no contract errors
in the current workspace. That proves the scanned manifest graph is internally
consistent; it does not prove every provider or production journey.

`govoplan-addresses@93dddbb8c52a` (`0.1.9` / `v0.1.9`) is an optional catalogued
extension for reusable recipient sources. It is not enabled in the pinned root
profile and must be added explicitly when the pilot needs address lists or
CardDAV.

## Recommended scenarios

### Campaign pilot

Use one internal tenant or office, controlled operators, local GovOPlaN accounts,
and non-critical recipient volumes. Enable:

```text
tenancy,organizations,identity,access,admin,dashboard,policy,audit,campaigns,files,mail,docs,ops
```

Add `addresses` only when reusable address books/lists or CardDAV are in scope.
Leave Calendar and Workflow out unless the pilot has an explicit journey for
them. The minimum topology is one supervised API process, one built WebUI, one
PostgreSQL database, durable local file storage, and one Redis/Celery worker when
asynchronous delivery is enabled. Use a dedicated non-production SMTP/IMAP
account and a restricted recipient allow-list.

### Small-production candidate

Use a reverse proxy/TLS endpoint, built WebUI assets, separately supervised API
and worker processes, PostgreSQL with measured backup/restore, Redis with
persistence, and durable shared or object storage. Run one scheduler only when a
selected module needs scheduled recovery. Multiple scheduler replicas require
leader election or an external lock, which is not established by this report.

This topology is a recommendation from the [Ops scalability profiles](https://git.add-ideas.de/GovOPlaN/govoplan-ops/src/branch/main/docs/SCALABILITY_PROFILES.md),
not a currently shipped production Compose/Kubernetes/systemd package.

## Functional capability matrix

| Capability | Status | Evidence and scope | Conditions, gaps, or exclusions |
| --- | --- | --- | --- |
| Module-aware API/WebUI composition | `verified` | Core registry tests cover installed manifests, route contribution, missing modules, and module permutations; the static contract scan passed; stable catalog sequence `202607220843` has a valid trusted signature and matching package refs. | Package integration is verified; repeat the module-permutation checks on the installed target composition. |
| Local tenants, accounts, sessions, API keys and RBAC | `verified` | Access/tenancy manifests, auth dependency tests, cookie/CSRF API smoke tests, and role/permission contracts. | External identity providers are not included in this conclusion. |
| Campaign draft authoring, validation, recipient import, build, execution snapshot and mock send | `verified` | Core API smoke tests exercise create/validate/build/mock-send, frozen delivery configuration, policy gates, job deltas and reconciliation; Campaign-focused tests passed; Campaign `v0.1.10` and Core `v0.1.13` are package-integrated in the signed stable catalog. | Code and package integration are verified; usability and target-provider acceptance remain separate. |
| Managed Campaign attachments and local file storage | `verified` | Files capability/route tests, Campaign attachment-build tests, and local-storage backend code. | The deployment must provide a durable path and include files in database/storage backup plans. |
| SMTP send, IMAP append and mailbox/profile policy | `available_unconfigured` | Mail adapters, encrypted profile model, helper tests, Campaign mail-policy smoke tests, and a GreenMail-oriented runbook/testbed. | No target mail server, TLS chain, throttling, sender policy, bounce/reply process, or real delivery receipt was exercised here. |
| Delivery retry, uncertainty and reconciliation | `partial` | Campaign API smoke tests include worker-loss/outcome-unknown reconciliation and frozen job evidence; those paths are present in catalogued Campaign `v0.1.10`. | A target-provider failure drill and operational alerting are still required; package integration does not prove provider behavior. |
| Reusable address lists and Campaign recipient-source integration | `available_unconfigured` | Address list/recipient capability and Campaign optional lookup tests passed; manifests expose optional interfaces. | `addresses` is not in the pinned profile. Configure permissions and data governance before use. |
| CardDAV address synchronization | `available_unconfigured` | Discovery, preview/conflict, two-way create/update/delete and disconnect tests passed in the current Addresses workspace. | Requires target-server interoperability, credentials, CA/TLS, rate-limit, conflict and restore drills. |
| File connectors (WebDAV/Nextcloud/Seafile/SMB/S3 import) | `partial` | Provider descriptors and browse/import helper tests exist; S3 connector tests passed. | Coverage varies by provider and optional dependency. No target content system was exercised; connector egress and provenance policy need review. |
| Local audit log and governed-event retry outbox | `verified` | Audit module contract plus enqueue/dispatch/failure-for-retry tests passed. | Central audit/SIEM export, retention enforcement and operational monitoring are not verified. |
| Configured-system documentation and Ops status pages | `verified` | Docs/Ops manifests contribute protected routes and WebUI packages; Ops code checks database, Redis, workers, storage and deployment-security settings. | This does not replace external monitoring or a target runbook. |
| Calendar/CalDAV integration | `partial` | Calendar `v0.1.8` supplies the catalogued storage/sync foundation. The durable external-write outbox, worker recovery, reconciliation, and retention work is committed, tested, and pushed on Calendar `main` after that tag. | The post-tag outbox work is remote-integrated source, not local-only WIP, but it is not in the signed stable package baseline and has not passed a target CalDAV drill. Bulk synchronized-calendar migration semantics remain separate work. |
| External LDAP/AD, OIDC/SAML or SCIM identity integration | `scaffold` | IDM owns normalized assignment APIs and documents connector boundaries. | Provider connectors, login callback flow and target directory reconciliation are not an implemented end-to-end capability. Use local accounts for this pilot. |
| Export-control/embargo-list screening | `planned` | Product-level [GovOPlaN #12](https://git.add-ideas.de/GovOPlaN/govoplan/issues/12) defines the consumer-independent user story. | No screening provider, list provenance, matching policy, review flow or legal evidence exists in this composition. |
| Workflow-driven journeys and views | `planned` | Workflow contracts/concepts exist outside this assessment. | Explicitly postponed. Do not include Workflow in pilot or production claims from this report. |

## Infrastructure matrix

| Component | Status | Current evidence | Target requirement / gap |
| --- | --- | --- | --- |
| WebUI and API | `verified` | FastAPI app, module routes, shared WebUI host, health endpoint, dev smoke and module-permutation tests; the catalog pins matching Core/Campaign backend and WebUI refs. | Materialize and supervise immutable artifacts in the target; no production image/service bundle is supplied here. |
| Background workers | `available_unconfigured` | Celery app, Campaign queues, Redis configuration and production-like launcher. | Run target broker/worker heartbeat and failure drills; split queues when provider limits or load justify it. |
| Scheduler | `partial` | A separately launched Celery beat process exists; Calendar recovery scheduling is committed and pushed after the catalogued `v0.1.8` tag. | The Calendar recovery slice is not stable-package-integrated. Keep single-instance until leader election/locking is proved; add process supervision and missed-schedule alerts. |
| PostgreSQL | `verified` | Production target in settings/operator docs, migration tracks and a disposable integration-check harness. | Target HA, patching, connection limits, WAL/archive policy and restore time are external deployment decisions. |
| Redis/queues | `available_unconfigured` | Redis-backed Celery configuration, health ping and append-only production-like container. | Target availability, persistence, eviction, authentication/TLS and queue-loss behavior were not assessed. |
| Local file storage | `verified` | Local backend, configured root, fallback-root tests and Ops writability check. | Suitable only for a durable single-node/shared path with backup; it blocks independent API scaling when node-local. |
| S3-compatible object storage | `partial` | S3 backend and connector code plus mocked browse/import tests. | Exercise the chosen service, credentials, CA, versioning, lifecycle, multipart/size behavior, restore and consistency expectations. |
| Reverse proxy and TLS | `external_system` | Core validates explicit CORS and secure-cookie posture; Ops reports unsafe production settings. | Deployment must provide certificates, proxy/header policy, request limits, logs and renewal monitoring. |
| Local identity and authorization | `verified` | Password/session/API-key/RBAC capabilities and tests. | Establish account lifecycle, MFA expectation, protected bootstrap and break-glass procedure. |
| Federated identity | `scaffold` | IDM boundary and assignment APIs. | Select and implement/test the actual OIDC/SAML/LDAP/SCIM path before requiring federation. |
| Application secret encryption | `verified` | Stable `MASTER_KEY_B64` contract and encrypted mail-credential paths. | Rotation and loss-recovery procedure need target validation. |
| Secret store and injection | `external_system` | Environment/file references are supported and templates avoid populated secrets. | Choose Vault/KMS/Kubernetes/systemd/environment mechanism, restrict access, rotate credentials and prevent secret exposure in logs/backups. |
| SMTP/IMAP and other connectors | `available_unconfigured` | Protocol adapters and development testbeds. | Target endpoints, egress, DNS, CA, throttling, service accounts and data-processing terms remain environment-specific. |
| Health/readiness | `verified` | `/health`, protected `/health/details`, and Ops checks for DB, Redis, workers, storage, maintenance and cookie/CORS posture. | Add external probes and distinguish liveness from dependency readiness for the chosen orchestrator. |
| Metrics, logs and alerting | `partial` | Correlation IDs, slow-request/query metrics in logs, worker inspection and operator status are implemented. | No bundled metrics exporter, log collector, dashboards, queue-depth alerts, pager route or SLO is verified. |
| Audit | `partial` | Local audit tables and retry outbox are verified. | Retention, tamper-evident export, privileged access review and SIEM integration are unproved. |
| Backup and restore | `partial` | Operator guide and installer hooks describe `pg_dump`/`pg_restore`; SQLite and simulated installer rollback drills exist. | [Core #29](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/29) remains open. No target PostgreSQL + files + secrets restore drill or measured RTO/RPO exists. |
| Disaster recovery | `not_assessed` | The Ops guide asks for RPO/RTO and restore drills. | No agreed RPO/RTO, off-site copy, failover topology, dependency recovery order, communications plan or exercise evidence was supplied. |

The scalability and sizing documentation delivered the documentation portions
of [Core #217](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/217) and
[Core #219](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/219).
[Core #28](https://git.add-ideas.de/GovOPlaN/govoplan-core/issues/28) records the
operator-documentation slice. These closed tickets are evidence of documented
models, not evidence that an organization's production environment has passed
them.

## Trust, data-flow and network boundaries

| Boundary / flow | Data and trust | Required controls |
| --- | --- | --- |
| Browser -> reverse proxy -> WebUI/API | Session and CSRF cookies, campaign content, recipient personal data and managed files cross the public/client boundary. | HTTPS, exact origins, secure cookies, request/body limits, tenant/RBAC enforcement, security headers and access logs. |
| API -> PostgreSQL | Tenants, identities, permissions, campaign drafts/snapshots/jobs, connector metadata and audit evidence enter the primary trusted data store. | Dedicated DB identity, encrypted transport where networked, least privilege, migration control, backup/restore and retention. |
| API/worker -> file/object storage | Campaign attachments and generated evidence may contain personal or confidential content. | Private buckets/paths, encryption, scoped credentials, malware/content policy where required, lifecycle and coordinated restore. |
| API -> Redis -> worker | Queue messages and job identifiers cross from request processing to an asynchronous trust zone. PostgreSQL remains the durable business-state authority. | Private/authenticated broker, bounded payloads, idempotent claims, queue monitoring and worker isolation. |
| Worker -> SMTP/IMAP | Recipient addresses, message bodies and attachments leave GovOPlaN; IMAP append stores a sent copy externally. | Approved service account, TLS/CA policy, recipient/sender policy, rate limits, outcome reconciliation and disclosure/legal basis. |
| Connector worker -> CardDAV/WebDAV/Seafile/SMB/S3/CalDAV | Address data, files or calendars cross an organizational/system boundary in both directions depending on connector mode. | Explicit direction, scoped credentials, endpoint allow-list, provenance, conflict policy, retry/reconciliation and target interoperability test. |
| Operator -> installer/catalog/migration plane | A highly privileged process can mutate packages, schemas and desired module state. | Separate operator identity, signed/pinned catalogs, maintenance mode, immutable run records, backups, rollback checks and restricted network access. |
| API/audit -> monitoring or SIEM | Operational metadata and potentially personal audit context may leave GovOPlaN. | Data minimization, retention/access policy, authenticated transport, integrity and documented processor/location. No sink is verified today. |

Typical network requirements are inbound HTTPS to the deployment proxy and
private connectivity from API/workers to PostgreSQL and Redis. Outbound access
may be required to SMTP submission, IMAP, HTTPS-based connectors/object storage,
DNS, NTP, certificate validation, monitoring and the signed module catalog.
Ports and destinations must come from the selected infrastructure; common
defaults such as PostgreSQL 5432, Redis 6379, SMTP 465/587 and IMAP 993 are not
an allow-list.

## Known assumptions, gaps and risks

Facts:

- The production-like profile is a development validation composition, not a
  production deployment artifact.
- The assessed package baseline is the trusted, signed stable catalog sequence
  `202607220843`; it pins Core `v0.1.13` and Campaign `v0.1.10`.
- Workflow is postponed.
- The default composition does not enable Addresses.
- Health/readiness checks exist; an external monitoring stack does not.

Assumptions that require confirmation:

- The pilot can use local accounts and one internal tenant/office.
- A controlled non-production SMTP/IMAP account and safe recipients are
  available.
- Campaign volume is below the measured limits of a single worker and database.
- Local durable storage is acceptable for the pilot and all recipient data has
  an approved legal basis and retention policy.

Highest risks:

1. A signed, reproducible package selection can still be installed or configured
   incorrectly and has not been accepted in the target environment.
2. Real SMTP/IMAP behavior, throttling and ambiguous outcomes have not been
   proven against the target provider.
3. Backup/restore and disaster recovery are not demonstrated across database,
   files, keys and deployment configuration.
4. External identity, monitoring, secret-store and reverse-proxy controls are
   deployment gaps rather than GovOPlaN-delivered components.
5. Post-tag Calendar work is committed and pushed but remains outside the signed
   stable package baseline; branch integration must not be mistaken for a
   release.
6. Data classification, retention, recipient consent/legal basis and external
   disclosure rules are not assessed for a concrete organization.

## Proof checks before promotion

1. Materialize the signed catalog into an isolated installation and rerun the
   contract, migration, module-permutation, and focused acceptance gates against
   the installed artifacts.
2. Run a target-like Campaign from import through validation, attachment build,
   queue, SMTP acceptance, IMAP append, reporting and audit using safe data.
3. Drill transient SMTP failure, accepted-but-local-commit-lost uncertainty,
   worker restart, Redis interruption and manual reconciliation without a
   duplicate send.
4. Restore PostgreSQL, managed files, configuration and encrypted credentials
   into an isolated environment; measure RPO and RTO.
5. Validate proxy/TLS, CORS, cookies, headers, body limits, account bootstrap,
   maintenance access and secret redaction.
6. Measure representative recipient/file volume, queue age, database growth,
   send rate and provider throttling; set capacity and alert thresholds.
7. Confirm audit/retention/privacy/legal requirements and any SIEM or archive
   export before using production personal data.

## Reusable assessment questionnaire

Answers should contain no secrets and no unnecessary personal data. Each answer
must be marked `answered`, `assumed`, `not_applicable`, or `not_assessed` and may
link evidence.

### Scope and outcomes

- What outcome and reference journey must GovOPlaN support?
- Which users, roles, tenants, organization units and delegated functions take
  part?
- Which journey steps are mandatory, optional, manual, external, or explicitly
  postponed?
- What constitutes pilot success and production acceptance?

### Data, privacy, records and policy

- Which data classes enter database, files, messages, calendars, addresses,
  logs and audit evidence?
- What are the legal basis, purpose, minimization, access, residency, retention,
  deletion, archive and legal-hold requirements?
- Which external systems/processors receive data, and in which jurisdictions?
- Which decisions require four-eyes approval, explainability or immutable
  evidence?

### Identity and integrations

- Are local accounts acceptable, or are OIDC, SAML, LDAP/AD or SCIM mandatory?
- What are the MFA, joiner/mover/leaver, service-account and break-glass rules?
- Which SMTP/IMAP, file/DMS, CardDAV/CalDAV, ERP, API or event endpoints are in
  scope? Record protocol/version, direction, auth, CA, rate limit and owner.
- Which integrations may be unavailable, and what degraded/manual behavior is
  acceptable?

### Workload and growth

- Tenants, named/active/concurrent users and peak requests?
- Campaigns per period, recipients per Campaign, send window, attachment sizes,
  import size and retry peak?
- Managed files, database and audit volume now and over the retention window?
- Connector batches, queue depth/age, scheduled jobs and external rate limits?

### Availability, hosting and operations

- Required service hours, planned maintenance, availability, RPO and RTO?
- Hosting, network zones, egress/proxy/DNS/NTP/CA, data-residency and
  air-gap constraints?
- Who operates PostgreSQL, Redis, storage, TLS, identity, secrets, monitoring,
  backups and incident response?
- What deployment, patch, migration, rollback, restore and DR drills must pass?

### Procurement and decisions

- Required open-source/license, support, accessibility, security, certification,
  interoperability and procurement conditions?
- Which requirements are blockers, accepted risks, residual risks or later
  roadmap work?
- Who owns each decision, evidence item and next review date?

For every capability and infrastructure conclusion, record the requirement,
status from the controlled vocabulary, evidence scope, evidence links,
assumptions, gaps, risks, recommendation and proof check. Reassessment must pin a
new composition and review any row whose code, evidence, configuration or target
requirement changed.

### Repeatable release rerun

The release-aware rerun tool validates the machine-readable assessment against
its JSON Schema, verifies the catalog's Ed25519 signature against an
independently pinned local trust keyring, and separately verifies the canonical
hash of the published or candidate keyring pinned by the signed catalog. The
downloaded keyring is therefore never its own sole trust root. The tool compares
catalog sequence and module versions and—when local checkouts are available—checks
annotated release tags against assessed commits. For repositories represented in
signed `release.selected_units`, both the peeled commit and annotated tag-object
ID must match exactly; re-annotating an unchanged commit requires review.
Release drift produces a machine-readable list of affected capability and
infrastructure conclusions instead of silently carrying their prior status
forward:

```bash
./.venv/bin/python tools/assessments/capability-fit.py \
  --public \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json
```

Use `--catalog CATALOG --keyring PUBLISHED_OR_CANDIDATE_KEYRING
--trusted-keyring PINNED_LOCAL_KEYRING` for an offline or release-candidate
rerun. `GOVOPLAN_MODULE_PACKAGE_CATALOG_TRUSTED_KEYS_FILE` may provide the
independently managed local trust-root path instead. During key rotation this
local file may contain both current and `next` keys within their validity
windows. Only `active` and `next` entries are trusted; unknown statuses,
duplicate key IDs and malformed structured keyrings fail closed, while revoked,
disabled and retired entries are ignored. Do not establish this trust file by
downloading it in the same rerun. Public JSON responses are bounded to 16 MiB.
Use `--json` or `--output PATH` for automation. Evidence and report files are
written through a bounded same-directory atomic replacement, with mode `0600`
and file and directory `fsync`. All parent directories must already exist, no
parent component may be a symlink, and an existing symlink or non-regular output
target is rejected.

Exit status `0` means the assessed release metadata is current, `2` means
explicit review is required, and `1` means the schema or trust checks are
blocked. The machine report distinguishes independent signature trust,
published-keyring hash agreement, and local-tag proof. Local-tag proof is only
marked checked when every composition entry is available for comparison and was
attempted. A successful rerun proves only the assessment schema, signed catalog
metadata, published-keyring integrity and optional local tag provenance; it does
not prove installed artifacts, target providers, target infrastructure, or
production fitness. Those remain separate proof checks above.

### Installed-composition evidence

The same rerun can inspect the Python environment in which it executes and bind
that observation to the assessment and signed catalog:

```bash
./.venv/bin/python tools/assessments/capability-fit.py \
  --public \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --collect-installed-evidence /var/tmp/govoplan-installed-evidence.json \
  --output /var/tmp/govoplan-fit-review.json
```

The collector follows the strict version `0.4.0`
[`installed-composition-evidence.schema.json`](installed-composition-evidence.schema.json)
contract. It enumerates all installed distributions whose normalized name starts
with `govoplan-`, compares the enabled assessed package and module-manifest
versions, and identifies missing, duplicate and extra GovOPlaN distributions.
Those differences produce stable review targets for the affected composition
entries and evidence-backed conclusions.

For each distribution, the collector also:

- reads the installed wheel `RECORD` file directly, with a 4 MiB metadata bound,
  rather than relying on an interpreted distribution file list; missing files,
  duplicate or malformed declarations, mismatched declared sizes and hashes all
  prevent a `verified` result;
- verifies every supported SHA-256 wheel-payload declaration in that local
  metadata, within fixed limits of 256 GovOPlaN distributions, 10,000 files and
  512 MiB hashed per distribution, 50,000 files and 2 GiB hashed for one
  collection, and 64 MiB for any single file;
- accepts package-owned data-file targets below the installation prefix and
  declared `console_scripts`, while rejecting other traversal, undeclared
  scripts, paths outside the prefix and leaf symlinks before opening a file;
- reports pip-generated, unhashed `__pycache__/*.pyc` entries separately only
  when their derived source is a hashed payload entry, including generated
  files below a confined package-owned runtime-data prefix;
- labels every PEP 610 observation with the explicit
  `local-pep610-metadata` basis and distinguishes coherent declared Git commits
  and archive hashes from editable installs, local directories,
  package-index/unknown origins and malformed metadata;
- compares a non-editable VCS commit with the assessment commit and, when one is
  present, the signed catalog `selected_units` commit;
- derives two content identities from bytes it actually verifies: an
  install-stable identity for immutable wheel-declared files and a full
  installed-RECORD identity, while retaining only SHA-256 digests and counts;
- records only package/module identifiers, versions, bounded counters, hashes
  and stable error codes. It never writes direct URLs, paths, hostnames,
  usernames, exception text or file contents.

`RECORD` `verified` means complete matching coverage of the wheel payload
declared by the local metadata, not every runtime byte and not a release-origin
binding. The proof scope exposes the aggregate count of generated unhashed
bytecode; runtime activation remains unchecked. `RECORD` agreement proves that
payload files agree with installed metadata, but does not make self-consistent
metadata a trusted release origin. Similarly, a version string is not artifact
integrity. PEP 610 VCS metadata is accepted only for
`vcs: git`, a full 40–64 hexadecimal commit, one mutually exclusive provenance
form and a coherent bounded URL shape. Editable and directory-backed installs
remain mutable even when their small editable-install `RECORD` is valid. Archive
or index artifacts without a hash anchored by the assessed release remain
unanchored. A matching declaration is reported under
`installed_source_provenance` as local consistency only, with
`release_origin_bound: false` until the separate origin proof succeeds. A signed
catalog can contain `release.artifacts` identities computed directly from built,
bounded wheel files. Wheels with installer-transformed scripts or headers are
marked `requires_installer_receipt`; catalog metadata alone cannot attest those
post-install bytes. A role-scoped installer receipt instead binds the exact
installed-evidence digest, full installed payload identities, catalog archive
digests and canonical signed-catalog digest. The tool never accepts an installed
hash merely because the installed evidence asserted it.

Only evidence produced in-process by `--collect-installed-evidence` is a local
observation, and it must be no more than five minutes old (with at most 30
seconds of future clock skew) at the selected verification time. Use
`--installed-evidence PATH` to compare evidence collected in a separate
environment. Imported JSON without a valid independent installer receipt
carries a blocker: it can identify differences but cannot establish checked or
valid installed proof. A receipt signed by a separately provisioned installer
authority authenticates that exact imported evidence across the process
boundary. The proof scope records observation mode, collection/evaluation time,
receipt authentication, freshness, and whether evaluation used current time or
an explicit historical override. Evidence input and output are bounded to 4
MiB. Collection loads the `govoplan.modules` entry-point factories in order to
read module IDs and manifest versions; that executes installed GovOPlaN manifest
code. Run it only inside the installation being assessed and with the same
isolation expected for other installed-artifact acceptance checks. This
collector does not observe
which modules a running service activated, migrations, configuration, health,
or reference-journey behavior. Runtime activation therefore remains an explicit
unchecked boundary.

### Target, provider and production proof boundary

Installed evidence cannot approve a target environment, an external provider,
or production use. These scopes use a separate, expiring
[`capability-fit-boundary-evidence.schema.json`](capability-fit-boundary-evidence.schema.json)
bundle. The bundle is bound to the assessment ID, assessment release and exact
installed-evidence SHA-256 digest. It contains only opaque subject/control/result
IDs and content hashes, not endpoints, credentials, people or raw result files.

Boundary evidence is accepted only when at least one Ed25519 signature validates
against a separately provisioned
[`capability-fit-proof-authority-keyring.schema.json`](capability-fit-proof-authority-keyring.schema.json).
Each authority key explicitly lists the scopes it may attest. Target and provider
claims use `passed` or `failed`; production claims use `approved` or `rejected`.
One claim per scope, unique control/artifact IDs, `issued_at < expires_at`, current
validity and exact digest binding are mandatory. Any schema, binding, time,
signature or authority blocker leaves every supplied boundary claim unchecked;
one malformed authority member or invalid validity interval invalidates the
supplied authority set as a whole. An authorized negative result is checked but
requires review only after every prerequisite, including installed
release-origin binding, is established.
Signatures cover UTF-8 JSON with the `signatures` member omitted, object keys
sorted, compact `,`/`:` separators and non-ASCII characters escaped, matching
the tool's deterministic canonicalization.

```bash
./.venv/bin/python tools/assessments/capability-fit.py \
  --public \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --installed-evidence /srv/govoplan/evidence/installed.json \
  --boundary-evidence /srv/govoplan/evidence/target-proof.json \
  --boundary-authority-keyring /srv/govoplan/trust/proof-authorities.json \
  --expected-external-provider-subject provider-production
```

With `--installed-evidence`, this command performs comparison and proof-binding
diagnostics. Without an installer receipt, the imported document remains
unsigned, so neither it nor the boundary claim becomes accepted proof. Direct
in-process collection can match catalog-anchored artifact identities for wheels
without installer-transformed files. The installer-receipt flow below
authenticates a durable cross-process observation and is required for transformed
script/header payloads.

Issue a receipt only in the installation process performing the live collection.
The command refuses evidence supplied from a file and first validates the
assessment, independently trusted signed catalog, composition and RECORD bytes:

```bash
./.venv/bin/python tools/assessments/installer-receipt.py \
  --assessment /srv/govoplan/assessment.json \
  --catalog /srv/govoplan/catalogs/stable.json \
  --keyring /srv/govoplan/catalogs/keyring.json \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --receipt-id install:production:20260722 \
  --signing-key installer-production=/run/secrets/installer-ed25519.pem \
  --python-artifact govoplan-core=/srv/govoplan/staged/govoplan_core-0.1.13-py3-none-any.whl \
  --python-artifact govoplan-campaign=/srv/govoplan/staged/govoplan_campaign-0.1.10-py3-none-any.whl \
  --evidence-output /srv/govoplan/evidence/installed.json \
  --receipt-output /srv/govoplan/evidence/installer-receipt.json
```

Repeat `--python-artifact PACKAGE=/exact/consumed.whl` for every enabled
GovOPlaN distribution. The issuer reopens each exact wheel, verifies its archive
and payload identities against the signed catalog, and refuses a different
build with the same name and version. Receipt issuance must follow collection
within five minutes, and live verification must still fall inside that bounded
window; retain the pair for a reproducible historical review at its explicit
verification time.

Verify that durable pair with its separately managed trust root:

```bash
./.venv/bin/python tools/assessments/capability-fit.py \
  --catalog /srv/govoplan/catalogs/stable.json \
  --keyring /srv/govoplan/catalogs/keyring.json \
  --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \
  --installed-evidence /srv/govoplan/evidence/installed.json \
  --installer-receipt /srv/govoplan/evidence/installer-receipt.json \
  --installer-authority-keyring /srv/govoplan/trust/installer-authorities.json
```

Target-environment and production-approval claims must use the assessment's
`deployment_profile.id` as `subject_id`. External-provider claims require the
operator to supply a bounded opaque expected subject with
`--expected-external-provider-subject`; without it, such a claim remains
unchecked and blocks. Expected and observed IDs are retained in proof scope.

Both authority keyrings are governance trust roots. Installer receipt keys use
the strict
[`installer-receipt-authority-keyring.schema.json`](installer-receipt-authority-keyring.schema.json)
contract and may attest only `installed_release_origin`; their public material
must not be reused by catalog or boundary-proof authorities. Do not download or
generate them from the proof bundle being checked. The checker rejects
proof-authority public keys reused by either the published or independently
trusted catalog keyring, and rejects the same proof public-key material assigned
to multiple authority IDs. A malformed key, an invalid or empty validity
interval, or ambiguous key
identity invalidates the supplied authority set. Authority `not_after` is
exclusive. A target operator or approver must validate the referenced
drill/result artifacts before signing. The rerun verifies the
attestation and its bindings; it does not fetch or reinterpret those artifacts.
`--verification-time` exists only for reproducible historical review. Supplying
it always marks the machine and human report as a **HISTORICAL override**; callers
cannot relabel it as current. Live admission must omit it and use the actual
current time.

No boundary bundle or production authority has been supplied for this current
assessment. Target environment, provider and production proof therefore remain
explicitly unchecked rather than inferred from the local GreenMail journey,
source tests or signed release metadata.

## Evidence used in this slice

- [Production-like profile](../dev/production-like/README.md) and
  [Compose dependencies](../dev/production-like/docker-compose.yml)
- [Module contracts and install boundaries](MODULE_CONTRACTS_AND_INSTALLS.md)
- [Core deployment operator guide](https://git.add-ideas.de/GovOPlaN/govoplan-core/src/branch/main/docs/DEPLOYMENT_OPERATOR_GUIDE.md)
- [Ops scalability profiles](https://git.add-ideas.de/GovOPlaN/govoplan-ops/src/branch/main/docs/SCALABILITY_PROFILES.md)
- Actual module manifests in the pinned repositories and the static contract
  checker in this meta repository
- Core module-system/API smoke/auth/install-config tests, plus focused Campaign,
  Files, Mail, Audit and Addresses tests
- [Campaign delivery runbook](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/src/branch/main/docs/CAMPAIGN_DELIVERY_RUNBOOK.md)
- [Live signed stable catalog](https://govoplan.add-ideas.de/catalogs/v1/channels/stable.json)
  and [published keyring](https://govoplan.add-ideas.de/catalogs/v1/keyring.json),
  verified against a separately provisioned local trust keyring
- Annotated source tags `govoplan-core/v0.1.13` and
  `govoplan-campaign/v0.1.10`, including their catalogued Python and WebUI refs
- Installed-composition, boundary-proof and independently scoped proof-authority
  schemas plus their deterministic review tests; no current target or production
  proof bundle is asserted

Checks retained from the first assessment slice against its then-current
workspace:

- static manifest/interface contract scan: 43 contracts, 29 providers, no issues
- selected Core module-composition, auth/CSRF, health, Campaign journey,
  reconciliation and install-configuration tests: 14 passed
- Campaign tests: 14 passed
- Files tests: 14 passed
- Mail tests: 22 passed
- Audit tests: 5 passed
- Addresses tests: 14 passed (one non-failing SQLite resource warning)
- JSON Schema validation of the machine-readable assessment: passed

Refresh checks on 2026-07-22:

- live stable catalog sequence `202607220843`: valid Ed25519 signature trusted
  through `release-key-1`, no validator warnings
- current static contract scan: 43 modules, 33 providers, 19 requirements, no
  contract errors
- catalog-selected commits: Core `d487726f4d2c` at `v0.1.13` and Campaign
  `735e874bd03c` at `v0.1.10`; local and remote release refs agree
- Campaign's immutable `v0.1.10` tag object and peeled commit exactly match the
  remote tag and catalog record; Calendar durable outbox work is committed and
  pushed after catalogued `v0.1.8`
- JSON Schema validation of the refreshed machine-readable assessment: passed

These checks are evidence for the rows above; they are not a substitute for the
installed-release and target-environment proof checks.