Check for race condition when delete before a write finishes

Author: ezimuel

src/Persistence/DocumentStore.php

@@ -20,7 +20,13 @@
  */
 final class DocumentStore
 {
-    /** @var int[] PIDs of outstanding async child processes. */
+    /**
+     * PIDs of outstanding async child processes, keyed by nodeId.
+     * Keying by nodeId lets waitForNode() drain exactly one write without
+     * blocking every other in-flight write.
+     *
+     * @var array<int, int>  nodeId → PID
+     */
     private array $pendingPids = [];
 
     public function __construct(private readonly string $docsDir) {}
@@ -59,8 +65,8 @@ public function write(
                 $this->writeSync($nodeId, $docId, $text, $metadata);
                 exit(0);
             } else {
-                // Parent: record PID and return.
-                $this->pendingPids[] = $pid;
+                // Parent: record PID keyed by nodeId and return.
+                $this->pendingPids[$nodeId] = $pid;
                 return;
             }
         }
@@ -69,6 +75,25 @@ public function write(
         $this->writeSync($nodeId, $docId, $text, $metadata);
     }
 
+    /**
+     * Block until the async write for a specific node has completed.
+     *
+     * Use this before deleting a node's file so a late child write cannot
+     * recreate {nodeId}.bin after the unlink().
+     */
+    public function waitForNode(int $nodeId): void
+    {
+        if (!isset($this->pendingPids[$nodeId])) {
+            return;
+        }
+
+        if (function_exists('pcntl_waitpid')) {
+            pcntl_waitpid($this->pendingPids[$nodeId], $status);
+        }
+
+        unset($this->pendingPids[$nodeId]);
+    }
+
     /**
      * Block until every outstanding async write has completed.
      * Must be called before index files are written (see VectorDatabase::save()).

src/VectorDatabase.php

@@ -204,6 +204,11 @@ public function deleteDocument(string|int $id): bool
 
         // Delete document file from disk if persistence is enabled.
         if ($this->path !== null) {
+            // An async pcntl_fork child may still be writing {nodeId}.bin.
+            // Wait for that specific write to finish before unlinking so the
+            // child cannot recreate the file after we delete it.
+            $this->getDocumentStore()->waitForNode($nodeId);
+
             $docFile = $this->path . '/docs/' . $nodeId . '.bin';
             if (file_exists($docFile)) {
                 // Suppress PHP warning and handle failure explicitly to keep