From e3e0fdaab5a8b6521ce222a6739f7b359af8ddc2 Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Mon, 3 Aug 2026 05:00:37 +0200 Subject: [PATCH] Document provider recovery reconciliation --- README.md | 4 ++++ docs/SCALABILITY_PROFILES.md | 6 ++++++ src/govoplan_ops/backend/manifest.py | 2 +- 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b03261b..19d5c8f 100644 --- a/README.md +++ b/README.md @@ -54,3 +54,7 @@ tables. A drain request is durable and is observed on the node heartbeat: API readiness closes and workers stop taking new queue work. The Recovery panel shows operations requiring forward recovery or manual intervention; it does not claim that a production database backup exists. +For provider effects, Ops is the status and evidence-chain projection rather +than the reconciliation authority. Follow the owning module's bounded action: +for example, reconcile an unknown Mail SMTP command from provider evidence and +never retry the original effect merely because its caller state is incomplete. diff --git a/docs/SCALABILITY_PROFILES.md b/docs/SCALABILITY_PROFILES.md index 782e0b4..a5973bb 100644 --- a/docs/SCALABILITY_PROFILES.md +++ b/docs/SCALABILITY_PROFILES.md @@ -57,6 +57,12 @@ manual-intervention record means an operator must repair the current release or restore a separately verified coordinated backup. Ops does not convert that state into a safe rollback. +An `outcome_unknown` provider operation must be resolved in its owning module. +Mail SMTP and IMAP APPEND operations, for example, carry stable attempt IDs and +digest-only evidence; use Mail's command reconciliation with provider evidence. +Do not replay the original effect from Ops. Read-only Mail index/source scans +are fenced across nodes and may be repeated only after the prior fence closes. + For the `shared` profile, missing expected replicas, release/composition skew, unserved queues, or an invalid PostgreSQL connection budget are readiness errors. Stale historical records remain visible, but cannot downgrade one of diff --git a/src/govoplan_ops/backend/manifest.py b/src/govoplan_ops/backend/manifest.py index 071ac0a..61dc9d7 100644 --- a/src/govoplan_ops/backend/manifest.py +++ b/src/govoplan_ops/backend/manifest.py @@ -139,7 +139,7 @@ manifest = ModuleManifest( id="ops.runtime-coordination-and-recovery", title="Drain runtime nodes and inspect recovery evidence", summary="Ops projects shared runtime heartbeats, replica gaps, drain controls, and recovery states that require operator attention.", - body="Use the runtime table to identify stale or composition-skewed API and worker replicas. Drain before replacement so API readiness closes and workers stop taking new queue work; cancellation is available while the node is still draining. The recovery table reports durable Core recovery operations. A rejected operation is a verified provider rejection and needs no recovery; outcome-unknown and recovery-required operations still require reconciliation. Backup status separately projects only the sanitized deployment verification receipt: a verified status identifies a coordinated recovery point and isolated restore drill, while absent, expired, or invalid evidence blocks a release-changing migration.", + body="Use the runtime table to identify stale or composition-skewed API and worker replicas. Drain before replacement so API readiness closes and workers stop taking new queue work; cancellation is available while the node is still draining. The recovery table reports durable Core recovery operations. A rejected operation is a verified provider rejection and needs no recovery; outcome-unknown and recovery-required operations still require reconciliation through the owning module. Mail SMTP and IMAP APPEND entries use stable attempt identifiers and digest-only evidence: reconcile the Mail command from provider evidence, never by replaying the original effect from Ops. Backup status separately projects only the sanitized deployment verification receipt: a verified status identifies a coordinated recovery point and isolated restore drill, while absent, expired, or invalid evidence blocks a release-changing migration.", documentation_types=("admin", "user"), audience=("operator", "system_admin"), conditions=(