Sync wiki from project files

2026-08-07 11:24:22 +02:00
parent 95005cddbc
commit 33d2a202e4
9 changed files with 204 additions and 17 deletions
@@ -35,6 +35,7 @@ This page is generated from repository and product-directory project files.
 - [Repo-docs-POLICY-CONTRACTS](Repo-docs-POLICY-CONTRACTS) - `/mnt/DATA/git/govoplan-core/docs/POLICY_CONTRACTS.md`
 - [Repo-docs-POSTBOX-E2EE-ARCHITECTURE](Repo-docs-POSTBOX-E2EE-ARCHITECTURE) - `/mnt/DATA/git/govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md`
 - [Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY](Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY) - `/mnt/DATA/git/govoplan-core/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md`
+- [Repo-docs-RECORDS-FILING-CONTRACT](Repo-docs-RECORDS-FILING-CONTRACT) - `/mnt/DATA/git/govoplan-core/docs/RECORDS_FILING_CONTRACT.md`
 - [Repo-docs-RELEASE-DEPENDENCIES](Repo-docs-RELEASE-DEPENDENCIES) - `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`
 - [Repo-docs-REMOTE-WEBUI-BUNDLES](Repo-docs-REMOTE-WEBUI-BUNDLES) - `/mnt/DATA/git/govoplan-core/docs/REMOTE_WEBUI_BUNDLES.md`
 - [Repo-docs-SEARCH-EVENT-INDEXING-CONTRACT](Repo-docs-SEARCH-EVENT-INDEXING-CONTRACT) - `/mnt/DATA/git/govoplan-core/docs/SEARCH_EVENT_INDEXING_CONTRACT.md`
@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:142f41e74858b0a5299652d7 -->
+<!-- codex-wiki-sync:cfa5f6dfe4c343b5ce7df35e -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/CONFIGURATION_PACKAGES.md`.
 > Origin: `repository`.
@@ -166,7 +166,36 @@ The initial implementation includes provider-neutral orchestration helpers:

 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.
+fragments and applies them idempotently. Mail and Files also register providers
+for deployment configuration: Mail owns receipt-bound SMTP profiles and Files
+validates the deployment-owned managed-storage binding.
+
+### Deployment capability receipt
+
+The installer mounts a bounded, non-secret infrastructure receipt at the path
+named by `GOVOPLAN_DEPLOYMENT_CAPABILITIES_PATH`. Core validates that document
+once for configuration-package context and exposes typed capability and
+post-install-task records to providers. Invalid receipts fail closed. Endpoint
+metadata is sanitized, and secret fields may cross this boundary only as
+`env:VARIABLE_NAME` references.
+
+Feature providers remain responsible for their own semantics:
+
+- Mail can derive host and port from `mail.smtp`, collect missing non-secret
+  transport fields, and bind an existing credential-envelope id. It never
+  accepts or exports a username, password, token, or decrypted credential.
+- Files compares `files.storage` with the effective runtime backend, endpoint,
+  trust marker, bucket, and presence of referenced environment secrets. Storage
+  remains deployment-owned, so the provider reports `skip` when they agree and
+  blocks drift instead of rewriting process environment or storage credentials.
+- A system-scoped Mail profile requires system configuration authority. Tenant
+  scope is the conservative default.
+- Existing Mail configuration is preserved unless a reviewed fragment
+  explicitly selects `on_conflict: update`. Reapplying an unchanged fragment is
+  a no-op.
+
+Ops projects the same Core-validated receipt. It must not maintain a second
+parser with different validation or secret-handling rules.

 The admin wizard backend starts with these routes:

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:19ba0a5ad3b4f1f26d3549bf -->
+<!-- codex-wiki-sync:dda017aacc2d51470d3a7477 -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DATAGRID_SIZING_CONTRACT.md`.
 > Origin: `repository`.
@@ -43,7 +43,8 @@ the column remains stopped until the pointer crosses the same boundary again.

 ## Persistence

-Only the pixel layout resulting from an explicit user resize is persisted.
+Only the pixel layout resulting from an explicit user resize is persisted,
+together with the container width at which the user selected it.
 Persisted widths are keyed by a signature containing column IDs, declared
 widths and bounds, resize affordances, sticky placement, initial fit, and resize
 behavior. A changed signature discards the old override and recomputes the
@@ -51,8 +52,13 @@ declared layout.

 Container reconciliation is suspended while a pointer drag is active. On
 release, the already-rendered pixel layout becomes the persisted preference.
-Reconciliation may grow it to prevent underflow, but never shrinks intentional
-user overflow, so there is no drag-end snap.
+Reconciliation at that same container width never shrinks intentional user
+overflow, so there is no drag-end snap. If the surrounding layout later
+contracts, persisted tracks may shrink toward their hard minima. The layout
+retains only the amount of horizontal overflow deliberately created by the
+user; an exact-cover layout therefore remains exact-cover at narrower widths.
+Legacy snapshots from the former hard-pixel persistence contract are discarded
+once and recomputed from the declared column layout.

 ## Regression Matrix

@@ -63,6 +69,7 @@ user overflow, so there is no drag-end snap.
 - hard-minimum horizontal overflow;
 - fixed-only cover grids;
 - persisted overrides under growth and viewport pressure;
+- responsive contraction of persisted layouts without losing deliberate overflow;
 - stale layout signatures;
 - first and middle-column right-side compensation;
 - last-resizable-column overflow, underflow stop, and reverse-pointer boundary;
@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:f357e8246adfdef6d50a3e37 -->
+<!-- codex-wiki-sync:6ead1cdff56d97939223b54a -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DEPLOYMENT_OPERATOR_GUIDE.md`.
 > Origin: `repository`.
@@ -285,12 +285,15 @@ through the same trusted address range.
 | --- | --- |
 | `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_MODULE_PACKAGE_CATALOG_APPROVED_CHANNELS` | Comma-separated approved catalog channels, for example `stable`. The legacy singular name remains readable during migration. |
 | `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.
+running WebUI. When no catalog override is configured, the Admin package
+directory uses GovOPlaN's public stable catalog and the trust anchor bundled
+with the installed Core release. Production operators may still pin a newer or
+institution-specific catalog/keyring explicitly with the settings above.

 ### Mail Test Credentials

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:794f1910b9dc31a0103bfeee -->
+<!-- codex-wiki-sync:bc5cbccfa421eee1f79956d4 -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`.
 > Origin: `repository`.
@@ -24,6 +24,7 @@ operator, and roadmap pages.
 | Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. |
 | External references and integration maturity | `EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md` | Stable external identity and cumulative connector maturity; configured source authority is defined by the meta target architecture. |
 | Institutional context and governed references | `INSTITUTIONAL_CONTEXT_CONTRACT.md` | Shared temporal, actor/representation, institution, mandate, service, party, decision, evidence, legal-basis, information-governance, presentation, and geo DTO/provider contracts. |
+| Provider-neutral record filing | `RECORDS_FILING_CONTRACT.md` | Exact source-revision identity, current source authorization, idempotent filing, capability discovery, and ownership boundary. |
 | Temporal data read context | `TEMPORAL_DATA_CONTEXT.md` | Valid-time and recorded-time titlebar selection, HTTP/cache contract, security boundary, and module-adoption rule. |
 | Cross-module information governance adoption | `INFORMATION_GOVERNANCE_ADOPTION.md` | Manifest evidence and enforcement rules for temporal browsing, purpose-aware access, retention, and institutional context. |
 | Context-sensitive F1 help | `CONTEXTUAL_HELP_CONTRACT.md` | Focus, route, module-manifest documentation contexts, Docs projection, and hosted fallback. |
@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:754dca1bc8283d2d296f9b31 -->
+<!-- codex-wiki-sync:cab04395a4581e602b99bc71 -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/MODULE_ARCHITECTURE.md`.
 > Origin: `repository`.
@@ -1384,8 +1384,10 @@ The package install-plan API records operator intent only:
 - `GET /api/v1/admin/system/modules/package-catalog` reads approved package
  references from `GOVOPLAN_MODULE_PACKAGE_CATALOG` so operators can add known
  module refs to the install plan without typing them manually. The endpoint
-  also reports catalog validity, channel, signature, trust state, and the
-  configured path.
+  also reports catalog validity, channel, signature, trust state, source and
+  artifact provenance, release availability, configuration requirements, and
+  per-entry compatibility/blocker state. Withdrawn entries are visible for
+  diagnosis but cannot be planned.
 - `POST /api/v1/admin/system/modules/install-plan/catalog/{module_id}` saves
  a planned install or update row from a validated catalog entry. Installed
  modules are planned as updates. Catalog signature and approved-channel policy
@@ -1483,6 +1485,10 @@ The installer preflight is intentionally conservative:
 - the `shared` state profile blocks in-place package mutation; clustered
  installations must roll one verified immutable module composition across all
  replicas;
+- official runtime images carry the full verified package profile, while the
+  desired module graph controls activation and tenant/View/Policy contracts
+  control availability and presentation; package lifecycle must not be reused
+  as a tenant or user visibility switch;
 - installed module manifests must be compatible with the supported manifest
  contract and current core version;
 - uninstalling `tenancy`, `access`, or `admin` is blocked;
@@ -0,0 +1,101 @@
+<!-- codex-wiki-sync:3efb4aa4dc0780d9658e716d -->
+
+> Mirrored from `/mnt/DATA/git/govoplan-core/docs/RECORDS_FILING_CONTRACT.md`.
+> Origin: `repository`.
+> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
+
+---
+# Records Filing Contract
+
+Core exposes a small provider-neutral contract for filing exact source
+revisions into an institutional record. Core does not own records semantics,
+source-object authorization, or source bytes. `govoplan-records` owns filing
+orchestration and chronology; each source module owns resolution of its exact
+revision.
+
+## Capability Names
+
+- `records.filing` is supplied by the enabled Records module.
+- `records.source.<module>` is supplied by an enabled source module, for
+  example `records.source.files` or `records.source.cases`.
+- `records.archive.<provider>` is supplied by an enabled archive-transfer
+  adapter. Discovery does not imply conformance or current health.
+
+Callers discover capabilities through the module registry. They must not
+import optional source-module internals.
+
+## Exact Source Identity
+
+`RecordSourceLocator` identifies one tenant, source module, resource type,
+resource ID, and immutable source revision. A source provider must:
+
+1. reject cross-tenant resolution;
+2. require a non-empty purpose;
+3. re-evaluate the caller's current module and object authorization;
+4. resolve exactly the requested revision, never a mutable "current" alias;
+5. return safe display/provenance metadata and a SHA-256 digest when the source
+   has stable bytes or a canonical snapshot;
+6. fail closed when the revision is missing, quarantined, corrupt, or no longer
+   authorized.
+
+Historical Records browsing never revives historical access rights. The
+source's current authorization decision remains authoritative when filing.
+
+## Filing Semantics
+
+`RecordFilingRequest` binds the exact source to a record, purpose, filing
+reason, relationship, institutional context, and idempotency key. Records must
+persist source identity and resolution evidence together with the filing actor,
+represented capacity, valid time, recorded time, and immutable chronology.
+
+An idempotency key may replay only an identical request. A conflicting reuse
+must fail. Filing does not transfer ownership of source content and must not
+silently copy mutable source state.
+
+## Versioning
+
+The Python DTOs and protocols live in `govoplan_core.core.records`. The
+manifest interface `records.filing` starts at `1.0.0`. Incompatible DTO or
+behavior changes require a new interface version and release impact analysis;
+additional optional metadata remains backward compatible.
+
+## Initial Providers
+
+- Files resolves an exact managed `FileVersion`, verifies current Files access
+  and blob integrity, and returns its stored content digest.
+- Cases resolves an exact immutable case revision after current case access and
+  returns a digest of the canonical revision snapshot.
+
+Provider-specific selection UI belongs to the source module. The generic
+Records dialog remains a diagnostic/manual fallback for exact identifiers.
+
+## Archive Transfer Boundary
+
+`RecordTransferPackage` binds a stable package ID, record revision, provider
+profile, canonical manifest, and manifest SHA-256. An archive provider exposes
+`RecordArchiveProviderState` before dispatch and accepts only a
+`RecordArchiveTransferRequest` for a declared healthy profile. Its receipt must
+identify the same package and provider and return one bounded outcome:
+`accepted`, `rejected`, or `outcome_unknown`.
+
+An unknown outcome is never retry-safe. Callers must retain the intent and
+reconcile it against the provider before another effect. Provider state also
+declares authority mode, freshness, limitations, and whether the provider is a
+simulation. Credentials, transport configuration, archive-specific package
+schemas, and custody semantics remain provider-owned.
+
+Records includes `records.archive.simulation` to prove package and receipt
+handling. The simulation is explicitly non-conformant, transfers no custody,
+and cannot be used as evidence of an archive handoff. A real provider requires
+a selected target/profile, provider-specific recovery declaration, and target
+test evidence.
+
+## Form Evidence Boundary
+
+Form attachments use the separate provider-neutral contract in
+`govoplan_core.core.form_evidence`. Forms Runtime requests short-lived,
+purpose-bound upload grants and re-inspects the exact provider-owned evidence
+before final submission. The provider keeps byte storage, quarantine,
+classification, and retention ownership; Forms Runtime stores only immutable
+evidence references and bounded verification results. This contract is not an
+alternative path for Records filing or archive custody.
@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:b1a4a97e73c58ed652f42a29 -->
+<!-- codex-wiki-sync:29fbd26651e01c2d851bf22f -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md`.
 > Origin: `repository`.
@@ -204,6 +204,13 @@ 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.

+If neither source is configured, the Admin package directory discovers the
+official public stable catalog at
+`https://govoplan.add-ideas.de/catalogs/v1/channels/stable.json`. Core verifies
+that fallback against the public key pinned in the installed Core package. An
+explicit deployment catalog always takes precedence; a configured source that
+is unavailable or invalid fails closed instead of silently falling back.
+
 An official catalog is a JSON object with:

 - `catalog_version`
@@ -219,6 +226,14 @@ Each module entry can declare:

 - backend package name and pinned install reference
 - WebUI package name and pinned install reference
+- `artifact_integrity` for each package, including the HTTPS registry URL,
+  filename, byte size, SHA-256, package identity, source tag, and source commit
+- `source`, binding the repository and immutable tag/commit identity, with
+  optional HTTPS repository and revision links
+- `availability`, either `available` or `withdrawn`; a withdrawn entry must
+  carry an operator-readable `availability_reason` and cannot be planned
+- `configuration_requirements` and an optional HTTPS `release_notes_url` for
+  prerequisites and release-specific operator guidance
 - display metadata and tags
 - `license_features`, the feature entitlements required to plan that install
 - `dependencies` and `optional_dependencies`, the module ids expected in the
@@ -246,6 +261,12 @@ Each module entry can declare:
 - `requires_interfaces`, named interface contracts and version ranges required
  by this module

+Core validates these fields before exposing the directory. Admin derives a
+read-only catalog state from the installed package set, catalog dependency
+closure, named-interface providers, current-version window, availability, and
+generic license policy. This is an early operator diagnostic; trusted installer
+preflight remains the authoritative mutation gate.
+
 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.
@@ -309,6 +330,12 @@ Catalog provenance changes preflight severity:
  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
+- a saved catalog plan must match the currently validated entry exactly;
+  altered package refs, artifact identities, channel, sequence, trust state, or
+  signing-key identity block the run and require replanning
+- a trusted remote artifact is downloaded before mutation into a private
+  SHA-256-addressed installer cache, checked for exact size and digest, and
+  passed to `pip` or npm only as that verified local file
 - 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
@@ -526,6 +553,11 @@ Catalog entries can require license features:
 Core checks those requirements against an offline license file before allowing
 the entry into the install plan.

+Official open-source GovOPlaN entries do not declare license features. The
+license contract remains generic for external catalogs, deployment presets,
+configuration/package directories, and support offerings; it gates only an
+entry that explicitly asks for a feature.
+
 ```bash
 GOVOPLAN_LICENSE_FILE=/srv/govoplan/license.json
 GOVOPLAN_LICENSE_ENFORCEMENT=true
@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:87320eb0e82f9897b4fd8744 -->
+<!-- codex-wiki-sync:d9978830a74fcad9f2f3ec95 -->

 > Mirrored from `/mnt/DATA/git/govoplan-core/docs/STATE_AND_RECOVERY_CONTRACT.md`.
 > Origin: `repository`.
@@ -100,10 +100,17 @@ Alembic, and post-migration tasks. The lock is session-scoped and therefore
 released if the migration process dies.

 Runtime roles run `govoplan_core.commands.wait_for_database`. It waits until
-the database has exactly the configured Core/module Alembic heads and never
-upgrades schema. This permits a migration Job and runtime Deployments to be
+the database has exactly the configured, dependency-resolved Core/module
+Alembic heads and never upgrades schema. Cross-module `depends_on` revisions
+therefore do not leave runtime roles waiting for a branch marker Alembic has
+correctly consumed. This permits a migration Job and runtime Deployments to be
 submitted together while keeping startup fail-closed.

+Runtime coordination records the installed `govoplan-core` distribution
+version for API, worker and scheduler roles. FastAPI/OpenAPI metadata versions
+are presentation metadata and must not be used as deployable software identity;
+mixing the two would create a false version-skew readiness failure.
+
 ## Recovery Ledger

 `govoplan_core.core.recovery` provides a durable operation and evidence