feat: enhance position calculation with error handling and jitter mechanism

Author: ManukMinasyan

src/Concerns/HasCardSchema.php

@@ -32,6 +32,7 @@ public function getCardSchema(Model $record): ?Schema
         }
 
         $livewire = $this->getLivewire();
+        /** @phpstan-ignore argument.type (Filament Schema expects HasSchemas&Livewire\Component but getLivewire returns HasBoard) */
         $schema = Schema::make($livewire)->record($record);
 
         return $this->evaluate($this->cardSchemaBuilder, ['schema' => $schema]);
@@ -42,6 +43,7 @@ public function getCardSchema(Model $record): ?Schema
      */
     protected function resolveDefaultClosureDependencyForEvaluationByName(string $parameterName): array
     {
+        /** @phpstan-ignore argument.type (Filament Schema expects HasSchemas&Livewire\Component but getLivewire returns HasBoard) */
         return match ($parameterName) {
             'schema' => [Schema::make($this->getLivewire())],
             default => parent::resolveDefaultClosureDependencyForEvaluationByName($parameterName),

src/Concerns/InteractsWithBoard.php

@@ -259,7 +259,7 @@ protected function calculateAndUpdatePositionWithRetry(
 
                 // Log the conflict for monitoring
                 Log::info('Position conflict detected, retrying', [
-                    'card_id' => $card->id,
+                    'card_id' => $card->getKey(),
                     'target_column' => $targetColumnId,
                     'attempt' => $attempt,
                     'max_attempts' => $maxAttempts,
@@ -302,54 +302,6 @@ protected function isDuplicatePositionError(QueryException $e): bool
                str_contains($e->getMessage(), 'UNIQUE constraint failed');
     }
 
-    /**
-     * Execute position update with retry mechanism for race conditions.
-     * Handles cases where rapid card movements cause stale data issues.
-     *
-     * @template T
-     *
-     * @param  callable(): T  $callback
-     * @return T
-     */
-    protected function withPositionRetry(callable $callback, string $cardId, string $targetColumnId, int $maxAttempts = 3): mixed
-    {
-        $baseDelay = 50; // milliseconds
-        $lastException = null;
-
-        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
-            try {
-                return $callback();
-            } catch (QueryException $e) {
-                if (! $this->isDuplicatePositionError($e)) {
-                    throw $e;
-                }
-
-                $lastException = $e;
-
-                Log::info('Position conflict detected, retrying', [
-                    'card_id' => $cardId,
-                    'target_column' => $targetColumnId,
-                    'attempt' => $attempt,
-                    'max_attempts' => $maxAttempts,
-                ]);
-
-                if ($attempt >= $maxAttempts) {
-                    throw new MaxRetriesExceededException(
-                        "Failed to move card after {$maxAttempts} attempts due to position conflicts",
-                        previous: $e
-                    );
-                }
-
-                $delay = $baseDelay * pow(2, $attempt - 1);
-                usleep($delay * 1000);
-
-                continue;
-            }
-        }
-
-        throw $lastException ?? new \RuntimeException('Unexpected retry loop exit');
-    }
-
     public function loadMoreItems(string $columnId, ?int $count = null): void
     {
         $count = $count ?? $this->getBoard()->getCardsPerColumn();

src/Services/DecimalPosition.php

@@ -4,6 +4,8 @@
 
 namespace Relaticle\Flowforge\Services;
 
+use InvalidArgumentException;
+
 /**
  * Decimal-based position calculation using BCMath for precision.
  * Uses DECIMAL(20,10) storage - 10 integer digits + 10 decimal places.
@@ -15,7 +17,7 @@
  * a unique position to prevent collisions when multiple users move cards
  * to the same position simultaneously.
  */
-final class DecimalPosition
+final readonly class DecimalPosition
 {
     /**
      * Default gap between positions (65,535).
@@ -76,10 +78,18 @@ public static function before(string $position): string
      *
      * @param  string  $after  Lower bound position (card above)
      * @param  string  $before  Upper bound position (card below)
-     * @return string  Position between bounds with jitter applied
+     * @return string Position between bounds with jitter applied
+     *
+     * @throws InvalidArgumentException When after >= before (invalid bounds)
      */
     public static function between(string $after, string $before): string
     {
+        if (bccomp($after, $before, self::SCALE) >= 0) {
+            throw new InvalidArgumentException(
+                "Invalid bounds: after ({$after}) must be less than before ({$before})"
+            );
+        }
+
         // Calculate the exact midpoint
         $sum = bcadd($after, $before, self::SCALE);
         $midpoint = bcdiv($sum, '2', self::SCALE);
@@ -106,10 +116,18 @@ public static function between(string $after, string $before): string
      *
      * @param  string  $after  Lower bound position
      * @param  string  $before  Upper bound position
-     * @return string  Exact midpoint between bounds
+     * @return string Exact midpoint between bounds
+     *
+     * @throws InvalidArgumentException When after >= before (invalid bounds)
      */
     public static function betweenExact(string $after, string $before): string
     {
+        if (bccomp($after, $before, self::SCALE) >= 0) {
+            throw new InvalidArgumentException(
+                "Invalid bounds: after ({$after}) must be less than before ({$before})"
+            );
+        }
+
         $sum = bcadd($after, $before, self::SCALE);
 
         return bcdiv($sum, '2', self::SCALE);
@@ -172,7 +190,7 @@ public static function generateSequence(int $count): array
      * Normalize a position string to ensure consistent format.
      * Converts numeric values to properly scaled decimal strings.
      */
-    public static function normalize(string|int|float $position): string
+    public static function normalize(string | int | float $position): string
     {
         return bcadd((string) $position, '0', self::SCALE);
     }
@@ -220,7 +238,7 @@ public static function gap(string $lower, string $upper): string
      * @param  string  $after  Lower bound position
      * @param  string  $before  Upper bound position
      * @param  int  $count  Number of positions to generate
-     * @return array<int, string>  Array of unique positions
+     * @return array<int, string> Array of unique positions
      */
     public static function generateBetween(string $after, string $before, int $count): array
     {
@@ -252,7 +270,7 @@ public static function generateBetween(string $after, string $before, int $count
      * desired range using BCMath for precision.
      *
      * @param  string  $maxOffset  Maximum absolute offset (positive number)
-     * @return string  Random value in [-maxOffset, +maxOffset]
+     * @return string Random value in [-maxOffset, +maxOffset]
      */
     private static function generateJitter(string $maxOffset): string
     {
@@ -261,14 +279,19 @@ private static function generateJitter(string $maxOffset): string
             return '0.0000000000';
         }
 
-        // Get 8 random bytes and convert to unsigned 64-bit integer
+        // Get 8 random bytes and convert to unsigned 64-bit string
+        // PHP's unpack('P') returns signed int for values >= 2^63,
+        // so we manually convert bytes to an unsigned decimal string
         $bytes = random_bytes(8);
-        $randomInt = unpack('P', $bytes)[1]; // Unsigned 64-bit little-endian
+        $randomUnsigned = '0';
+        for ($i = 7; $i >= 0; $i--) {
+            $randomUnsigned = bcmul($randomUnsigned, '256', 0);
+            $randomUnsigned = bcadd($randomUnsigned, (string) ord($bytes[$i]), 0);
+        }
 
-        // Normalize to [0, 1] range
-        // PHP_INT_MAX is the max for signed, but we have unsigned so use 2^64
+        // Normalize to [0, 1] range using 2^64 - 1 as max
         $maxUint64 = '18446744073709551615'; // 2^64 - 1
-        $normalized = bcdiv((string) $randomInt, $maxUint64, self::SCALE);
+        $normalized = bcdiv($randomUnsigned, $maxUint64, self::SCALE);
 
         // Scale to [-1, 1] range
         $scaled = bcsub(bcmul($normalized, '2', self::SCALE), '1', self::SCALE);

src/Services/PositionRebalancer.php

@@ -16,7 +16,7 @@
  * This service redistributes positions evenly using the default gap, ensuring
  * consistent spacing and preventing precision exhaustion after many insertions.
  */
-final class PositionRebalancer
+final readonly class PositionRebalancer
 {
     /**
      * Rebalance all positions in a column.