Sync wiki from project files

2026-08-07 11:36:32 +02:00
parent 92840678d6
commit 2caf6fe6b2
+27 -2
@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:9e345fdac830d07aeab8038e --> <!-- codex-wiki-sync:78dc86887a155825811383e5 -->
> Mirrored from `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`. > Mirrored from `/mnt/DATA/git/govoplan/docs/INSTALLATION_AND_DEPLOYMENT_ARCHITECTURE.md`.
> Origin: `repository`. > Origin: `repository`.
@@ -106,6 +106,7 @@ The private installation directory contains:
| `existing-proxy.json` | Exact upstream, trusted-source, header, and health contract for an operator-owned proxy | | `existing-proxy.json` | Exact upstream, trusted-source, header, and health contract for an operator-owned proxy |
| `plan.json` | Latest desired-state diff and readiness findings | | `plan.json` | Latest desired-state diff and readiness findings |
| `receipt.json` | Last successfully applied immutable identities | | `receipt.json` | Last successfully applied immutable identities |
| `infrastructure-capabilities.json` | Deterministic non-secret capability states, endpoint metadata, secret references, consumers, and resumable post-install tasks |
| `distribution-manifest.json` | Canonical signed runtime/image selection adopted by the installer | | `distribution-manifest.json` | Canonical signed runtime/image selection adopted by the installer |
| `distribution-keyring.json` | Explicitly installed public trust anchor for runtime releases | | `distribution-keyring.json` | Explicitly installed public trust anchor for runtime releases |
| `backup-evidence.json` | Signed provider-neutral coordinated backup and isolated-restore receipt | | `backup-evidence.json` | Signed provider-neutral coordinated backup and isolated-restore receipt |
@@ -119,6 +120,16 @@ The private installation directory contains:
The specification contract is The specification contract is
[`installation-spec.schema.json`](installation-spec.schema.json). [`installation-spec.schema.json`](installation-spec.schema.json).
The API, workers, scheduler, and Ops read the capability receipt through the
same bounded Core validator. Configuration-package providers receive that typed
receipt in preflight context. Mail uses `mail.smtp` to offer an idempotent SMTP
profile plan and accepts only an existing credential-envelope reference; Files
uses `files.storage` to prove that the deployment-owned local/S3 runtime binding
already matches. Files deliberately blocks drift instead of rewriting process
environment or initiating an implicit object migration. Invalid receipts fail
closed, while a deployment without a mounted receipt continues to run but
cannot apply receipt-bound configuration fragments.
Build the same dependency-free tool as one downloadable artifact: Build the same dependency-free tool as one downloadable artifact:
```sh ```sh
@@ -415,16 +426,24 @@ the supported topology and promotion path.
## Reconfiguration Semantics ## Reconfiguration Semantics
`installation.json` is desired state. `receipt.json` is the last successfully `installation.json` is desired state. `receipt.json` is the last successfully
applied state. `plan` compares their canonical hashes and service sets. applied state. `plan` compares their canonical hashes, service sets, and
infrastructure capability projections.
- Adding a managed component creates its service and persistent volume. - Adding a managed component creates its service and persistent volume.
- Removing a component removes its service container on apply. - Removing a component removes its service container on apply.
- Replacing or removing a capability adds a review action that names the prior
and desired state/source plus declared module consumers. This does not claim
that the deployer can inspect module-owned database configuration; the
operator must review that inventory before apply.
- Volumes are retained by default; deleting data requires a separate, - Volumes are retained by default; deleting data requires a separate,
deliberately destructive workflow. deliberately destructive workflow.
- Existing generated credentials are retained unless an explicit future rotate - Existing generated credentials are retained unless an explicit future rotate
operation is requested. operation is requested.
- Private configuration changes are represented by a keyed fingerprint in the - Private configuration changes are represented by a keyed fingerprint in the
plan and receipt; plaintext values are never copied there. plan and receipt; plaintext values are never copied there.
- Capability documents contain sanitized scheme/host/port metadata and stable
`env:` references only. Credential values and secret-bearing URLs remain in
`secrets.env` or module-owned credential envelopes.
- Managed-to-external transitions require the new endpoint in the same - Managed-to-external transitions require the new endpoint in the same
operation. operation.
- Migrations run as a one-shot service before API/worker replacement. - Migrations run as a one-shot service before API/worker replacement.
@@ -437,6 +456,12 @@ applied state. `plan` compares their canonical hashes and service sets.
- Health must recover before a new receipt and applied-state snapshot are - Health must recover before a new receipt and applied-state snapshot are
committed. committed.
Compose mounts the capability document read-only into API and worker runtime
containers. The Kubernetes export projects the same document through a
dedicated ConfigMap and read-only file mount. Ops validates the bounded schema
before displaying configured, externally supplied, available-unconfigured, or
unavailable states and any pending post-install tasks.
Every apply operation is journalled before image pulls or runtime mutation. A Every apply operation is journalled before image pulls or runtime mutation. A
failure before migration may restore a verified previous bundle. Once migration failure before migration may restore a verified previous bundle. Once migration
starts, recovery is forward-only unless an independently verified database starts, recovery is forward-only unless an independently verified database