fix: Remove unsupported $not operator and clarify limitations

- Remove incomplete $not operator implementation
- Throw clear error if $not is used
- Update documentation to reflect limitation
- Recommend using $ne for field-level negation instead
- All 290 tests still passing

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

docs/filter-syntax.md

@@ -190,12 +190,20 @@ const results = await repo.find({
 
 ### NOT
 
+> **Note**: The `$not` operator is not currently supported when using the backward-compatible translation layer. Use `$ne` (not equal) for field-level negation instead.
+
 ```typescript
+// ❌ Not supported
+const results = await repo.find({
+  filters: {
+    $not: { status: 'deleted' }
+  }
+});
+
+// ✅ Use $ne instead
 const results = await repo.find({
   filters: {
-    $not: {
-      status: 'deleted'
-    }
+    status: { $ne: 'deleted' }
   }
 });
 ```
@@ -297,7 +305,6 @@ const urgentTasks = await repo.find({
 | `$exist` | Field exists | `{ metadata: { $exist: true } }` |
 | `$and` | Logical AND | `{ $and: [{...}, {...}] }` |
 | `$or` | Logical OR | `{ $or: [{...}, {...}] }` |
-| `$not` | Logical NOT | `{ $not: {...} }` |
 
 ## Migration Guide
 

packages/foundation/core/src/repository.ts

@@ -89,15 +89,10 @@ export class ObjectRepository {
             nodes.push(...this.interleaveWithOperator(orNodes, 'or'));
         }
 
+        // Note: $not operator is not currently supported in the legacy FilterNode format
+        // Users should use $ne (not equal) instead for negation on specific fields
         if (filter.$not) {
-            // NOT operator: convert to array of negated conditions
-            // This is a simplification - proper implementation would need driver support
-            const notNode = this.convertFilterToNode(filter.$not);
-            if (nodes.length > 0) {
-                nodes.push('and');
-            }
-            // Wrap in array to indicate it's a NOT group
-            nodes.push(['not', notNode]);
+            throw new Error('$not operator is not supported. Use $ne for field negation instead.');
         }
 
         // Process field conditions