spec: add harden-hourly-sync-lifecycle change (WealthLedger/backend#56)

2026-10-12 20:28:58 +03:00
parent 78f01066d2
commit 14174a7bb3
11 changed files with 828 additions and 0 deletions
@@ -0,0 +1,23 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+  participant TB as T-Bank and public sources
+  participant API as Resource GET
+
+  Coordinator->>DB: Reserve attempt for current connection
+  DB-->>Coordinator: Attempt with connection revision
+  Coordinator->>Steps: Run required steps (membership, portfolios, operations, events)
+  Steps->>TB: Fetch missing data
+  Steps->>DB: Publish complete successful step result
+  Steps->>DB: Record terminal step result (success or failure with code)
+  Coordinator->>DB: Read step results after terminal barrier
+  alt All required steps succeeded
+    Coordinator->>DB: Settle succeeded
+  else Some required steps succeeded
+    Coordinator->>DB: Settle partial with safe problem sections
+  else No required step succeeded
+    Coordinator->>DB: Settle failed with safe problem sections
+  end
+  API->>DB: Read last attempt result
+  DB-->>API: Time, outcome, safe problem list
@@ -0,0 +1,24 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+  participant TB as T-Bank and public sources
+
+  Coordinator->>Steps: Run required steps
+  Steps->>TB: Start upstream call
+  Coordinator->>Coordinator: Wait for step result within bound
+  alt Step reaches terminal result in time
+    Steps->>DB: Publish complete result
+    Coordinator->>DB: Settle attempt after terminal barrier
+  else Wait bound expires
+    Note over Coordinator,TB: Upstream call is not cancelled
+    Coordinator->>DB: Record step problem cause DEADLINE
+    Coordinator->>DB: Settle partial or failed after terminal barrier
+    Steps->>TB: Upstream call completes later
+    Steps->>DB: Publish late result for the same attempt
+    alt Outcome not recorded yet and no successor
+      DB-->>Steps: Late result is preserved and counts at outcome derivation
+    else Successor attempt already started
+      DB-->>Steps: Publication rejected as stale
+    end
+  end
@@ -0,0 +1,23 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+
+  Note over Coordinator,DB: Attempt is still running but its walk no longer executes
+  Coordinator->>DB: Detect running attempt without active walk
+  alt Process still alive after lost settle
+    Coordinator->>DB: Read actual step results
+    Coordinator->>DB: Close attempt as partial or failed with cause INTERRUPTED
+  else Process restarted after stop
+    Coordinator->>DB: Read actual step results
+    Coordinator->>DB: Close abandoned attempt as partial or failed with cause INTERRUPTED
+  end
+  DB-->>Coordinator: Attempt is terminal, no overlap possible
+  Coordinator->>DB: Reserve next attempt at next hourly term from attempt start
+  alt Next term reached
+    DB-->>Coordinator: Successor attempt starts
+    Steps->>DB: Late publication from previous attempt
+    DB-->>Steps: Publication rejected as stale relative to successor
+  else Next term not reached
+    DB-->>Coordinator: No work (not-due)
+  end