diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index c7bddfe..e9e6d9b 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -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` diff --git a/Repo-docs-CONFIGURATION-PACKAGES.md b/Repo-docs-CONFIGURATION-PACKAGES.md index 0af87b6..f193dfc 100644 --- a/Repo-docs-CONFIGURATION-PACKAGES.md +++ b/Repo-docs-CONFIGURATION-PACKAGES.md @@ -1,4 +1,4 @@ - + > 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: diff --git a/Repo-docs-DATAGRID-SIZING-CONTRACT.md b/Repo-docs-DATAGRID-SIZING-CONTRACT.md index b4edfce..954642b 100644 --- a/Repo-docs-DATAGRID-SIZING-CONTRACT.md +++ b/Repo-docs-DATAGRID-SIZING-CONTRACT.md @@ -1,4 +1,4 @@ - + > 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; diff --git a/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md b/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md index d737f0a..4ecd142 100644 --- a/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md +++ b/Repo-docs-DEPLOYMENT-OPERATOR-GUIDE.md @@ -1,4 +1,4 @@ - + > 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 diff --git a/Repo-docs-DOCUMENTATION-MAP.md b/Repo-docs-DOCUMENTATION-MAP.md index e91235f..70b4709 100644 --- a/Repo-docs-DOCUMENTATION-MAP.md +++ b/Repo-docs-DOCUMENTATION-MAP.md @@ -1,4 +1,4 @@ - + > 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. | diff --git a/Repo-docs-MODULE-ARCHITECTURE.md b/Repo-docs-MODULE-ARCHITECTURE.md index 19ce5e4..77bf5b7 100644 --- a/Repo-docs-MODULE-ARCHITECTURE.md +++ b/Repo-docs-MODULE-ARCHITECTURE.md @@ -1,4 +1,4 @@ - + > 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; diff --git a/Repo-docs-RECORDS-FILING-CONTRACT.md b/Repo-docs-RECORDS-FILING-CONTRACT.md new file mode 100644 index 0000000..d3a61ae --- /dev/null +++ b/Repo-docs-RECORDS-FILING-CONTRACT.md @@ -0,0 +1,101 @@ + + +> 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.` is supplied by an enabled source module, for + example `records.source.files` or `records.source.cases`. +- `records.archive.` 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. diff --git a/Repo-docs-RELEASE-DEPENDENCIES.md b/Repo-docs-RELEASE-DEPENDENCIES.md index d3cf066..d9b57cc 100644 --- a/Repo-docs-RELEASE-DEPENDENCIES.md +++ b/Repo-docs-RELEASE-DEPENDENCIES.md @@ -1,4 +1,4 @@ - + > 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 diff --git a/Repo-docs-STATE-AND-RECOVERY-CONTRACT.md b/Repo-docs-STATE-AND-RECOVERY-CONTRACT.md index 00f03d6..2946bc6 100644 --- a/Repo-docs-STATE-AND-RECOVERY-CONTRACT.md +++ b/Repo-docs-STATE-AND-RECOVERY-CONTRACT.md @@ -1,4 +1,4 @@ - + > 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