chore(8.0): final pre-RC1 sweep — API consistency, named errors, orphans, zero-cast codebase

src/transaction/operations/IndexOperations.ts

@@ -50,13 +50,26 @@ export class AddToHNSWOperation implements Operation {
   }
 
   /**
-   * Check if item exists in index
+   * Check if item exists in index.
+   *
+   * `getItem` is an optional, feature-detected provider capability — see the
+   * VectorIndexProvider docs; it is intentionally absent from the required
+   * contract (Brainy's JS HNSW index omits it). When the capability is
+   * missing the answer must be `false`, not `true`: treating unknowable
+   * pre-existence as "existed" made every rollback skip removeItem, leaving
+   * phantom entries in the index after a failed transaction. The safe default
+   * is to remove what this operation added — update flows pair this op with a
+   * RemoveFromHNSWOperation whose own rollback restores the prior vector, so
+   * reverse-order rollback reconstructs the original state either way.
    */
   private async itemExists(id: string): Promise<boolean> {
+    const index = this.index as JsHnswVectorIndex & {
+      getItem?: (id: string) => Promise<unknown>
+    }
+    if (typeof index.getItem !== 'function') return false
     try {
-      // Try to get item - if exists, no error
-      await (this.index as any).getItem?.(id)
-      return true
+      const item = await index.getItem(id)
+      return item !== undefined && item !== null
     } catch {
       return false
     }