fix(orm): ensure ORM::class and ORMInterface::class return same instance

Fixes #752: Resolves container binding issue where ORM::class and ORMInterface::class
returned different instances, causing 'duplicate key value violation' errors
during entity updates when both binding types were used.

🐛 Problem:
- ORMInterface::class was registered as singleton
- ORM::class was not explicitly bound, causing Laravel to create new instances
- Different ORM instances led to entity manager conflicts
- Users getting different object hashes: spl_object_hash() mismatch

🔧 Solution:
- Added ORM::class binding that returns ORMInterface::class singleton
- Ensures both $app->get(ORM::class) and $app->get(ORMInterface::class) return same instance
- Prevents entity manager conflicts and duplicate key violations

🧪 Testing:
- Added comprehensive test reproducing the issue
- Test verifies object hash equality: spl_object_hash() matches
- Test verifies object identity: assertSame() passes
- All existing ORM registration tests continue to pass

Thanks to @mm-sol for reporting this issue and providing detailed
reproduction steps and initial solution direction.

Closes #752

Author: lotyp

.cursor/development-guidelines.md

@@ -51,6 +51,51 @@ This document provides guidelines for effective AI-assisted development based on
    - Understand why issues occur
    - Research best practices and proven solutions
 
+### 🐛 Community Issue Handling
+
+#### **TDD Bug Fix Process**
+
+1. **Analyze Issue** 🔍 — Understand root cause and impact
+2. **Create Failing Test** ❌ — Reproduce the exact problem
+3. **Implement Fix** 🔧 — Apply minimal solution with clear comments
+4. **Validate Fix** ✅ — Ensure test passes and no regressions
+5. **Commit with Attribution** 📝 — Credit contributor and link issue
+
+#### **Attribution Best Practices**
+
+```php
+// Fix #XXX: Brief explanation (@contributor-username)
+```
+
+#### **Laravel Container Best Practices**
+
+```php
+// ✅ Use proper Laravel container mechanisms
+$app->alias(InterfaceClass::class, ConcreteClass::class);  // Alias for same instance
+$app->singleton(ConcreteClass::class, $factory);          // Register singleton
+
+// ❌ Avoid type mismatches and manual workarounds
+$app->bind(ConcreteClass::class, function ($app): ConcreteClass {
+    return $app->get(InterfaceClass::class); // Type error!
+});
+```
+
+#### **Commit Message Format for Bug Fixes**
+
+```bash
+fix(scope): brief description
+
+Fixes #XXX: Detailed explanation
+
+🐛 Problem: [what was wrong]
+🔧 Solution: [what was changed]
+🧪 Testing: [how it was validated]
+
+Thanks to @contributor-username for reporting and solution direction.
+
+Closes #XXX
+```
+
 ## 💻 Code Quality Standards
 
 ### 🧪 Testing Philosophy

.cursor/testing-guidelines.md

@@ -480,6 +480,105 @@ public function it_renders_orm_schema(): void
 }
 ```
 
+## 🧪 TDD Bug Fix Approach
+
+### 🐛 **Community Issue Resolution Process**
+
+When handling community-reported bugs, follow this proven TDD approach:
+
+#### **Step 1: Issue Analysis** 🔍
+
+```bash
+# Analyze the reported issue thoroughly
+# - Read the bug description and reproduction steps
+# - Examine affected code files
+# - Understand the root cause and impact
+```
+
+#### **Step 2: Create Failing Test** ❌
+
+```php
+/**
+ * This test reproduces issue #XXX - Brief description
+ *
+ * @see https://github.com/wayofdev/laravel-cycle-orm-adapter/issues/XXX
+ * @author contributor-username
+ */
+#[Test]
+public function it_reproduces_the_reported_issue(): void
+{
+    // Reproduce the exact issue as reported
+    $result1 = $this->app->get(SomeInterface::class);
+    $result2 = $this->app->get(ConcreteClass::class);
+
+    // This should fail initially, proving the bug exists
+    $this::assertSame($result1, $result2, 'Meaningful error message explaining expected behavior');
+}
+```
+
+#### **Step 3: Implement Fix** 🔧
+
+```php
+// Apply the minimal fix using proper Laravel container mechanisms
+// ✅ Good: Use Laravel's alias for interface-to-concrete mapping
+$app->alias(InterfaceClass::class, ConcreteClass::class);
+
+// ❌ Avoid: Manual binding with type mismatches
+$app->bind(ConcreteClass::class, function ($app): ConcreteClass {
+    return $app->get(InterfaceClass::class); // Type mismatch!
+});
+```
+
+#### **Step 4: Validate Fix** ✅
+
+```bash
+# Run the specific test to confirm it now passes
+docker compose run --rm --no-deps app vendor/bin/pest --filter="test_method_name"
+
+# Run related tests to ensure no regressions
+docker compose run --rm --no-deps app vendor/bin/pest tests/path/to/related/tests/
+```
+
+#### **Step 5: Commit with Attribution** 📝
+
+```bash
+git commit -m "fix(scope): brief description
+
+Fixes #XXX: Detailed explanation of the issue and solution
+
+🐛 Problem:
+- Specific issue description
+- Impact on users
+- Root cause analysis
+
+🔧 Solution:
+- What was changed
+- Why this approach was chosen
+- How it prevents the issue
+
+🧪 Testing:
+- Test that reproduces the issue
+- Test validation of the fix
+- Regression testing results
+
+Thanks to @contributor-username for reporting this issue and providing
+detailed reproduction steps and solution direction.
+
+Closes #XXX"
+```
+
+### 🎯 **Example: Issue #752 Resolution**
+
+This approach was used to resolve [issue #752](https://github.com/wayofdev/laravel-cycle-orm-adapter/issues/752):
+
+1. **Issue**: `ORM::class` and `ORMInterface::class` returned different instances
+2. **Test**: Created test verifying `spl_object_hash()` equality
+3. **Fix**: Used `$app->alias(ORMInterface::class, ORM::class)` - proper Laravel container mechanism
+4. **Validation**: Test passes, PHPStan clean, no regressions in 39 provider tests
+5. **Attribution**: Credited @mm-sol in comments and commit message
+
+**Key Lesson**: Use Laravel's `alias()` method instead of manual bindings to avoid type mismatches.
+
 ## 🔍 Testing Best Practices
 
 ### ✅ **DO This**
@@ -567,6 +666,39 @@ $this->app->instance(ORMInterface::class, $mockOrm);
 $orm = $this->app->make(ORMInterface::class);
 ```
 
+### 💬 **Code Comments in Tests**
+
+#### **When to Add Comments**
+
+```php
+// ✅ For community issue reproduction tests
+/**
+ * Test for issue #752: Brief description of the problem.
+ * @author contributor-username
+ */
+
+// ✅ For complex business logic tests
+/**
+ * Validates complex relationship cascade behavior when parent is soft-deleted.
+ */
+
+// ✅ For non-obvious test setup
+// Create circular reference to test relationship handling
+$user->addFriend($friend);
+$friend->addFriend($user);
+```
+
+#### **When to Skip Comments**
+
+```php
+// ❌ Don't comment obvious tests
+#[Test]
+public function it_creates_user(): void // Don't add "// Test user creation"
+
+// ❌ Don't over-explain simple assertions
+$this::assertEquals('John', $user->getName()); // Don't add "// Check name equals John"
+```
+
 ## 🚨 Troubleshooting & Debugging
 
 ### 🐳 **Docker Issues**

src/Bridge/Laravel/Providers/Registrators/RegisterORM.php

@@ -62,6 +62,9 @@ public function __invoke(Application $app): void
                 $app->get(ORMInterface::class)
             );
         });
+
+        // Fix #752: Alias ORM::class to ORMInterface::class singleton (@mm-sol)
+        $app->alias(ORMInterface::class, ORM::class);
     }
 
     private function shouldLoadEntityBehavior(): bool

tests/src/Bridge/Laravel/Providers/Registrators/RegisterORMTest.php

@@ -16,6 +16,8 @@
 use Psr\Container\NotFoundExceptionInterface;
 use WayOfDev\Tests\TestCase;
 
+use function spl_object_hash;
+
 class RegisterORMTest extends TestCase
 {
     #[Test]
@@ -82,4 +84,23 @@ public function it_disables_entity_behavior_by_default(): void
 
         $this::assertInstanceOf(CommandGenerator::class, $class->getCommandGenerator());
     }
+
+    /**
+     * @throws ContainerExceptionInterface
+     * @throws NotFoundExceptionInterface
+     */
+    #[Test]
+    public function it_returns_same_instance_for_concrete_class_and_interface(): void
+    {
+        $ormInterface = $this->app->get(ORMInterface::class);
+        $ormConcrete = $this->app->get(ORM::class);
+
+        $this::assertSame(
+            spl_object_hash($ormInterface),
+            spl_object_hash($ormConcrete),
+            'ORM::class and ORMInterface::class should return the same instance to prevent entity manager conflicts'
+        );
+
+        $this::assertSame($ormInterface, $ormConcrete);
+    }
 }