GovOPlaN/govoplan
1
0
Fork 0
Code Issues 10 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: refresh capability release baseline

Browse Source
This commit is contained in:
Albrecht Degering
2026-07-22 15:21:27 +02:00
parent 5447299289
commit c29f1e9977
2 changed files with 152 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md
View File

@@ -4,10 +4,10 @@
| Field | Value |
| --- | --- |
| Assessment ID | `campaign-reference-2026-07-20` |
| Assessment ID | `campaign-reference-2026-07-22` |
| Schema | `govoplan.fit-assessment/0.1.0` |
| Assessed on | 2026-07-20 |
| Product snapshot | Untagged workspace at meta commit `05ae81d64195`; this is not a release artifact |
| 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 |
@@ -20,11 +20,11 @@ manifest existing. A conclusion needs code plus a route/contract, test,
operational drill, configured example, or explicit evidence that the capability
is absent.
The checkout contained unrelated uncommitted work when this assessment was
made. A dirty repository is recorded below, but local-only changes do not count
as an integrated release capability. Tests run against the dirty workspace are
useful implementation evidence and are labelled as such; they do not turn the
workspace into a reproducible release.
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
@@ -51,12 +51,13 @@ 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.
It is not yet possible to call the current workspace a supported small-production
distribution. 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/add-ideas/govoplan-core/issues/29)
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/add-ideas/govoplan-core/issues/29)
is a production gate. Identity federation, external audit export, and a tested
disaster-recovery plan are also not complete.
@@ -64,43 +65,48 @@ 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 a clean, pinned release candidate.
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`. Module versions come from the actual manifests. `Dirty`
means that repository had uncommitted changes at assessment time.
`ENABLED_MODULES`. Versions and refs below are pinned by the live stable catalog;
commits are the commits peeled from those annotated tags.
| Module | Repository commit | Manifest version | Dirty | Role in this assessment |
| --- | --- | ---: | :---: | --- |
| Core runtime | `govoplan-core@e6f7c45f0a95` | server `0.3.0` | yes | API, registry, migration orchestration, shared WebUI, sessions and kernel contracts |
| `tenancy` | `govoplan-tenancy@1dde03854733` | 0.1.8 | no | tenant context and lifecycle |
| `organizations` | `govoplan-organizations@45cda1a33f18` | 0.1.8 | no | organization model |
| `identity` | `govoplan-identity@7a1710af896f` | 0.1.8 | yes | normalized internal identity directory |
| `access` | `govoplan-access@ab07075a679b` | 0.1.8 | yes | local authentication, sessions, API keys and RBAC |
| `admin` | `govoplan-admin@c9e1fb287f50` | 0.1.8 | no | administration surfaces |
| `dashboard` | `govoplan-dashboard@a315a7c62b1d` | 0.1.8 | no | module-aware home surface |
| `policy` | `govoplan-policy@2511fbb5a864` | 0.1.8 | no | policy explanation/configuration boundary |
| `audit` | `govoplan-audit@5e4f84a789ea` | 0.1.8 | no | database audit records and retrying audit outbox |
| `campaigns` | `govoplan-campaign@2e593b7fa412` | 0.1.8 | yes | Campaign authoring, build, delivery control and reporting |
| `files` | `govoplan-files@f3210234d35a` | 0.1.8 | yes | managed files and Campaign attachments |
| `mail` | `govoplan-mail@b0337b2d261a` | 0.1.8 | yes | SMTP/IMAP profiles and transports |
| `calendar` | `govoplan-calendar@371a00aff51c` | 0.1.8 | yes | optional calendar; not needed by the Campaign pilot |
| `docs` | `govoplan-docs@f2ade1d62475` | 0.1.8 | yes | configured-system documentation |
| `ops` | `govoplan-ops@341773a4ff8a` | 0.1.8 | no | readiness and deployment-profile visibility |
| 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 |
No tagged release or configuration package is pinned. That is a reproducibility
gap, not a harmless omission. The static contract scan found 43 interface
contracts, 29 providers, and no contract errors in this workspace. This proves
the scanned manifest graph is internally consistent; it does not prove the
behavior of every repository in that graph.
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@f19350e65d76` (manifest 0.1.8, dirty) is an optional 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.
`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
@@ -135,18 +141,18 @@ not a currently shipped production Compose/Kubernetes/systemd package.
| 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. | The pinned workspace is dirty and untagged; repeat on a clean release candidate. |
| 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 in this workspace. | Current Campaign UI/code also contains substantial unintegrated WIP; usability and release integration need separate acceptance. |
| 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. | A target-provider failure drill and operational alerting are still required; local Campaign audit-proof work is not release-integrated. |
| 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 storage/sync tests exist; durable external-write outbox, worker recovery and retention are local WIP in this snapshot. | Not required for the Campaign pilot and must not be treated as release-integrated yet. Bulk synchronized-calendar migration semantics remain separate work. |
| 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/add-ideas/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. |
@@ -155,9 +161,9 @@ not a currently shipped production Compose/Kubernetes/systemd package.
| 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. | Build immutable, matching frontend/backend artifacts and supervise them; no production image/service bundle is supplied here. |
| 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 and Calendar recovery schedule exist in local WIP. | Keep single-instance until leader election/locking is proved; add process supervision and missed-schedule alerts. |
| 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. |
@@ -209,7 +215,8 @@ Facts:
- The production-like profile is a development validation composition, not a
production deployment artifact.
- The assessed workspace is untagged and several key repositories are dirty.
- 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.
@@ -225,22 +232,25 @@ Assumptions that require confirmation:
Highest risks:
1. A dirty, untagged workspace cannot be reproduced or promoted safely.
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. Local Campaign and Calendar WIP can look complete in the checkout while
remaining absent from the remote release baseline.
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. Create a clean release candidate that pins every module/package and WebUI
artifact; rerun the contract, module-permutation and focused test gates.
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,
@@ -332,8 +342,13 @@ requirement changed.
- 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/add-ideas/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 [trusted keyring](https://govoplan.add-ideas.de/catalogs/v1/keyring.json)
- Annotated source tags `govoplan-core/v0.1.13` and
`govoplan-campaign/v0.1.10`, including their catalogued Python and WebUI refs
Checks run for this first slice against the current workspace:
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,
@@ -345,5 +360,18 @@ Checks run for this first slice against the current workspace:
- 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
clean-release and target-environment proof checks.
installed-release and target-environment proof checks.