From 44bb3fe07ab191abd8260af6975bc175c223878e Mon Sep 17 00:00:00 2001
From: soryu <soryu@soryu.co>
Date: Sat, 31 Jan 2026 22:53:28 +0000
Subject: feat: Add contract management system improvements (Phase 1)

- Add docs/contract-management-spec.md with full system design
- Add docs/plans/implementation-plan.md with 5-phase rollout plan
- Add validate_deliverable() function and use in mark_deliverable_complete
- Add PhaseChangeResult enum and change_contract_phase_with_version() with FOR UPDATE locking
- Enforce phase_guard at API level for all callers

This addresses critical issues in contract management:
- Deliverable validation to prevent marking non-existent deliverables complete
- Version conflict detection for phase changes with row locking
- Phase guard enforcement at API level (applies to all callers including supervisors)
- Comprehensive specification and implementation plan for future phases
---
 makima/src/db/models.rs | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'makima/src/db/models.rs')

diff --git a/makima/src/db/models.rs b/makima/src/db/models.rs
index a6b5b05..636d81a 100644
--- a/makima/src/db/models.rs
+++ b/makima/src/db/models.rs
@@ -1808,6 +1808,37 @@ pub struct ChangePhaseRequest {
     /// User feedback for changes (used when not confirming)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub feedback: Option<String>,
+    /// Expected version for optimistic locking. If provided, the phase change
+    /// will only succeed if the current contract version matches.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expected_version: Option<i32>,
+}
+
+/// Result of a phase change operation, supporting explicit conflict detection.
+#[derive(Debug, Clone)]
+pub enum PhaseChangeResult {
+    /// Phase change succeeded, returning the updated contract
+    Success(Contract),
+    /// Version conflict: the contract was modified concurrently
+    VersionConflict {
+        /// The version the client expected
+        expected: i32,
+        /// The actual current version in the database
+        actual: i32,
+        /// The current phase of the contract
+        current_phase: String,
+    },
+    /// Validation failed (e.g., invalid phase transition)
+    ValidationFailed {
+        /// Human-readable reason for the failure
+        reason: String,
+        /// List of missing requirements for the phase transition
+        missing_requirements: Vec<String>,
+    },
+    /// The caller is not authorized to change this contract's phase
+    Unauthorized,
+    /// The contract was not found
+    NotFound,
 }
 
 /// Response for phase transition when phase_guard is enabled
-- 
cgit v1.2.3