Release 0.10.2: three entity-manager and schema-mapper fixes

All three are behind non-default features or affect types a default build never
reaches, so nothing here changes a default-feature project.

Two unsaved entities registered with an entity manager aliased each other.
`tide_pk_key` is infallible and has no notion of "unsaved", so a default primary
key renders as an ordinary string — "0" for an i64. `register` and `put` filed
entities under it, so the second new instance of a model collided with the first
and was handed the first one back: a `HasMany` holding two new children silently
dropped one and inserted the other twice. `TideEntityManagerMeta` gains
`tide_pk_is_new`, defaulting to false so hand-written impls are unaffected, and
both call sites return early rather than aliasing.

`persist` left an identity-map entry no path could remove. `persisted_key`
answered two different questions — whether a row exists in the database, and
which key the entry is filed under in the identity map. They diverge for an
entity given to `persist` with a client-assigned primary key, which is trackable
immediately but not yet inserted. All three removal paths keyed off
`persisted_key`, so `detach` silently did nothing and `remove` plus a flush left
`find_managed` returning a row that was never written. The map key is now its own
field, threaded through flush, detach and checkpoint rollback; the DELETE stays
gated on whether a row actually exists.

`Text` and `JsonArray` are exported from `tideorm::types` and documented as model
field types, and `canonical_schema_type` already normalised both names, but
neither had an arm in the `ColumnType` match — so both reached the catch-all and
failed to compile.

Four regression tests, each checked to fail against the unfixed code. They are
deliberately database-free: the entity-manager ones use a disconnected handle,
and the removal test drives the entry's own flush rather than
`EntityManager::flush`, which opens a transaction. Putting database-requiring
tests in the lib suite is what broke CI two releases ago.

Author: mohamadzoh

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-08-25
+
+Three defects behind the `entity-manager` feature and the schema type mapper.
+Nothing here affects a default-feature build.
+
+### Added
+
+- `TideEntityManagerMeta::tide_pk_is_new`, reporting whether an entity's primary key is still the
+  type's default. It defaults to `false`, so hand-written implementations are unaffected; the derive
+  emits it from `ModelMeta::primary_key_is_new`.
+
+### Fixed
+
+- **Two unsaved entities registered with an entity manager aliased each other.** `tide_pk_key` is
+  infallible and has no notion of "unsaved", so it renders a default primary key as an ordinary
+  string — `"0"` for an `i64`. `register` and `put` filed entities under it, so the second new
+  instance of a model collided with the first and was handed the first one back. A `HasMany` holding
+  two new children silently dropped one and inserted the other twice. Both now return early for an
+  entity whose primary key is still new: it has no identity to share until the insert assigns one.
+- **`persist` left an identity-map entry that nothing could remove.** `persisted_key` answered two
+  different questions — whether a row exists in the database, and which key the entry is filed under
+  in the identity map. Those diverge for an entity given to `persist` with a client-assigned primary
+  key: trackable immediately, but not yet inserted. All three removal paths keyed off
+  `persisted_key`, so `detach` silently did nothing and `remove` + flush left a `find_managed`
+  returning a row that was never written. The map key is tracked separately now, while the `DELETE`
+  stays gated on whether a row actually exists.
+- **`Text` and `JsonArray` could not be used as model field types.** Both are exported from
+  `tideorm::types` and documented for model fields, and `canonical_schema_type` already recognised
+  the names, but neither had an arm in the `ColumnType` match — so both fell through to the
+  catch-all and failed to compile. `Vec<serde_json::Value>` is accepted for `JsonArray` too.
+
 ## [0.10.1] - 2026-08-25
 
 ### Changed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tideorm"
-version = "0.10.1"
+version = "0.10.2"
 edition = "2024"
 authors = ["Mohamad Al Zohbie <alzoubi528@gmail.com>"]
 description = "A developer-friendly ORM for Rust with clean, expressive syntax"
@@ -86,7 +86,7 @@ rust_decimal = { version = "1.41.0", features = ["serde"] }
 thiserror = "2.0.18"
 
 # Derive macros (our own crate)
-tideorm-macros = { version = "0.10.1", path = "tideorm-macros" }
+tideorm-macros = { version = "0.10.2", path = "tideorm-macros" }
 
 # Utils
 parking_lot = "0.12.5"

src/entity_manager/managed.rs

@@ -268,6 +268,17 @@ pub(crate) struct ManagedEntry<T> {
     snapshot: RwLock<Option<T>>,
     state: RwLock<EntityState>,
     persisted_key: RwLock<Option<String>>,
+    /// The key this entry is filed under in the manager's identity map.
+    ///
+    /// Deliberately separate from [`Self::persisted_key`], which answers a
+    /// different question: whether a row for this entity exists in the database.
+    /// The two coincide for a loaded entity but not for one handed to `persist`
+    /// with a client-assigned primary key — that is trackable immediately, so it
+    /// goes into the identity map, while nothing has been inserted yet. Keying
+    /// removal off `persisted_key` there left an entry no path could clear, so
+    /// `detach` did not detach and a later `find_managed` returned a row that had
+    /// never been written.
+    identity_key: RwLock<Option<String>>,
 }
 
 impl<T> ManagedEntry<T> {
@@ -281,10 +292,22 @@ impl<T> ManagedEntry<T> {
             current: RwLock::new(entity),
             snapshot: RwLock::new(snapshot),
             state: RwLock::new(state),
+            // A caller that already knows the persisted key is filing the entry
+            // under it; `persist` overrides this for the client-assigned case.
+            identity_key: RwLock::new(persisted_key.clone()),
             persisted_key: RwLock::new(persisted_key),
         }
     }
 
+    /// Record the identity-map key this entry was filed under.
+    pub(crate) fn set_identity_key(&self, key: Option<String>) {
+        *self.identity_key.write() = key;
+    }
+
+    pub(crate) fn identity_key(&self) -> Option<String> {
+        self.identity_key.read().clone()
+    }
+
     pub(crate) fn state(&self) -> EntityState {
         *self.state.read()
     }
@@ -324,10 +347,6 @@ impl<T> ManagedEntry<T> {
         *self.state.write() = EntityState::Removed;
     }
 
-    pub(crate) fn persisted_key(&self) -> Option<String> {
-        self.persisted_key.read().clone()
-    }
-
     fn mark_detached(&self) {
         *self.state.write() = EntityState::Detached;
     }
@@ -369,9 +388,12 @@ where
     }
 
     fn detach_from_context(&self, entity_manager: &EntityManager) {
-        if let Some(key) = self.persisted_key.read().as_ref() {
+        // `identity_key`, not `persisted_key`: an entity given to `persist` with a
+        // client-assigned primary key is in the map without having been inserted.
+        if let Some(key) = self.identity_key.read().as_ref() {
             entity_manager.remove_managed_entry::<T>(key);
         }
+        *self.identity_key.write() = None;
 
         self.mark_detached();
     }
@@ -383,6 +405,7 @@ where
             snapshot: self.snapshot.read().clone(),
             state: self.state(),
             persisted_key: self.persisted_key.read().clone(),
+            identity_key: self.identity_key.read().clone(),
         })
     }
 
@@ -393,8 +416,14 @@ where
         match self.state() {
             EntityState::Detached => Ok(()),
             EntityState::Removed => {
-                let key = self.persisted_key.read().as_ref().cloned();
-                if let Some(key) = key {
+                // Only a row that exists gets a DELETE, so that stays gated on
+                // `persisted_key`. Evicting from the identity map is a separate
+                // question and uses `identity_key`, which is also set for an
+                // entity `persist`ed under a client-assigned key and never
+                // inserted — without this it survived the remove and a later
+                // `find_managed` handed back a row that was never written.
+                let persisted = self.persisted_key.read().as_ref().cloned();
+                if let Some(key) = persisted {
                     let entity = self
                         .snapshot
                         .read()
@@ -406,11 +435,15 @@ where
                     )
                     .await?;
                     entity_manager.remove_by_entity_manager_key::<T>(&key);
-                    entity_manager.remove_managed_entry::<T>(&key);
+                }
+
+                if let Some(key) = self.identity_key.read().as_ref() {
+                    entity_manager.remove_managed_entry::<T>(key);
                 }
 
                 *self.snapshot.write() = None;
                 *self.persisted_key.write() = None;
+                *self.identity_key.write() = None;
                 self.mark_detached();
                 Ok(())
             }
@@ -422,7 +455,10 @@ where
                     None => true,
                 };
 
-                let previous_key = self.persisted_key.read().as_ref().cloned();
+                // The map entry may predate the insert: `persist` files a
+                // client-assigned key immediately. Evict under whatever it was
+                // actually filed as, not under the persisted key it may not have.
+                let previous_key = self.identity_key.read().as_ref().cloned();
                 let saved = if columns_changed {
                     save_with_entity_manager_impl(&current, entity_manager).await?
                 } else {
@@ -442,6 +478,7 @@ where
 
                 *self.current.write() = saved.clone();
                 *self.snapshot.write() = Some(saved.clone());
+                *self.identity_key.write() = next_key.clone();
                 *self.persisted_key.write() = next_key;
                 *self.state.write() = EntityState::Managed;
                 entity_manager.put(saved);
@@ -457,25 +494,29 @@ struct ManagedEntryCheckpoint<T> {
     snapshot: Option<T>,
     state: EntityState,
     persisted_key: Option<String>,
+    identity_key: Option<String>,
 }
 
 impl<T> ManagedCheckpoint for ManagedEntryCheckpoint<T>
 where
     T: Send + Sync + 'static,
 {
     fn rollback(self: Box<Self>, entity_manager: &EntityManager) {
-        if let Some(current_key) = self.entry.persisted_key.read().as_deref() {
+        // Both evict and re-file go through `identity_key`, which is what the map
+        // is actually keyed by; `persisted_key` is restored as plain state.
+        if let Some(current_key) = self.entry.identity_key.read().as_deref() {
             entity_manager.remove_managed_entry::<T>(current_key);
         }
 
-        if let Some(previous_key) = self.persisted_key.as_deref() {
+        if let Some(previous_key) = self.identity_key.as_deref() {
             entity_manager.put_managed_entry::<T>(previous_key, self.entry.clone());
         }
 
         *self.entry.current.write() = self.current;
         *self.entry.snapshot.write() = self.snapshot;
         *self.entry.state.write() = self.state;
         *self.entry.persisted_key.write() = self.persisted_key;
+        *self.entry.identity_key.write() = self.identity_key;
     }
 }
 

src/entity_manager/meta.rs

@@ -14,6 +14,22 @@ pub trait TideEntityManagerMeta {
 
     fn tide_pk_key(&self) -> String;
 
+    /// Whether this entity's primary key is still the type's default, i.e. no
+    /// row has been inserted for it yet.
+    ///
+    /// [`Self::tide_pk_key`] is infallible and has no notion of "unsaved", so it
+    /// renders a default key as an ordinary string — `"0"` for an `i64`. Every
+    /// unsaved instance of a model therefore produces the *same* identity key,
+    /// and filing two of them in the identity map makes the second collide with
+    /// the first. Callers that key the map must skip an entity for which this
+    /// returns `true`: it has no identity to share yet.
+    ///
+    /// Defaults to `false` for hand-written implementations, which preserves the
+    /// previous behaviour for anyone not deriving `Model`.
+    fn tide_pk_is_new(&self) -> bool {
+        false
+    }
+
     /// Tables a row of this model points at with a foreign key, so they have to
     /// hold a row before this one can be inserted.
     ///

src/entity_manager/mod.rs

@@ -168,6 +168,10 @@ impl EntityManager {
         self.register_managed_entry(entry.clone());
         if let Some(key) = key.as_deref() {
             self.put_managed_entry::<T>(key, entry.clone());
+            // Record what the entry was filed under. `persisted_key` stays `None`
+            // — nothing is inserted yet — so without this the removal paths, which
+            // all key off the map entry, would have nothing to evict.
+            entry.set_identity_key(Some(key.to_string()));
         }
         Managed::from_entry(entry)
     }
@@ -222,9 +226,14 @@ impl EntityManager {
     where
         T: Send + Sync + 'static,
     {
-        if let Some(key) = managed.entry.persisted_key() {
+        // `identity_key`, not `persisted_key`: an entity `persist`ed with a
+        // client-assigned primary key is in the identity map before any insert,
+        // so keying the eviction off the persisted key left it behind and the
+        // detach silently did nothing.
+        if let Some(key) = managed.entry.identity_key() {
             self.remove_managed_entry::<T>(&key);
         }
+        managed.entry.set_identity_key(None);
 
         managed.entry.mark_detached_public();
         self.remove_managed_ops_entry(managed);
@@ -418,6 +427,16 @@ impl EntityManager {
         let mut entity = entity;
         entity.tide_attach_entity_manager_database(self.database());
 
+        // An unsaved entity has no identity to share. `tide_pk_key` renders its
+        // default primary key as an ordinary string, so every new instance of a
+        // model keys to the same thing — file two of them and the second gets
+        // handed the first one back, which silently drops it and inserts the
+        // first twice. Hand it straight back instead; the flush files it under a
+        // real key once the insert assigns one.
+        if entity.tide_pk_is_new() {
+            return entity;
+        }
+
         let key = (TypeId::of::<T>(), entity.tide_pk_key());
 
         if let Some(existing) = self.get_by_key::<T>(&key) {

src/entity_manager/state.rs

@@ -133,6 +133,12 @@ impl EntityManager {
         let mut entity = entity;
         entity.tide_attach_entity_manager_database(self.database());
 
+        // Same collision as `register`: an unsaved entity's default primary key
+        // is not an identity, and filing several under it makes them alias.
+        if entity.tide_pk_is_new() {
+            return;
+        }
+
         let key = (TypeId::of::<T>(), entity.tide_pk_key());
         save::record_identity_map_rollback::<T>(self, &key);
         let mut map = self.identity_map.write();

tests/unit/entity_manager_mod_tests.rs

@@ -656,3 +656,99 @@ fn transaction_scope_is_restored_when_a_polled_future_panics() {
         "a panic must not leave the transaction scope pinned on this worker thread"
     );
 }
+
+/// Client-assigned primary key, so `persist` can file it in the identity map
+/// before anything is inserted — the case where "tracked" and "exists in the
+/// database" genuinely differ.
+#[tideorm::model(table = "entity_manager_mod_test_widgets")]
+struct EntityManagerModTestWidget {
+    #[tideorm(primary_key)]
+    id: i64,
+    name: String,
+}
+
+#[tokio::test]
+async fn detach_clears_an_entry_persisted_under_a_client_assigned_key() {
+    let entity_manager = Arc::new(EntityManager::new(Arc::new(Database::disconnected())));
+
+    let managed = entity_manager.persist(EntityManagerModTestWidget {
+        id: 42,
+        name: "widget".to_string(),
+    });
+
+    assert!(
+        entity_manager
+            .get_managed_by_key::<EntityManagerModTestWidget>("42")
+            .is_some(),
+        "persist should track a client-assigned primary key immediately"
+    );
+
+    entity_manager.detach(&managed);
+
+    // The eviction has to key off the map key, not `persisted_key`: nothing was
+    // inserted, so `persisted_key` is `None` and keying off it left the entry
+    // behind, making `detach` a no-op and a later `find_managed` hand back a row
+    // that never existed.
+    assert!(
+        entity_manager
+            .get_managed_by_key::<EntityManagerModTestWidget>("42")
+            .is_none(),
+        "detach must clear the identity-map entry it was filed under"
+    );
+}
+
+#[tokio::test]
+async fn removing_a_never_inserted_entity_evicts_it_without_a_delete() -> crate::error::Result<()> {
+    // The database is disconnected, so this also asserts the flush issues no
+    // DELETE for a row that was never written — it would fail if it tried.
+    let entity_manager = Arc::new(EntityManager::new(Arc::new(Database::disconnected())));
+
+    let managed = entity_manager.persist(EntityManagerModTestWidget {
+        id: 77,
+        name: "widget".to_string(),
+    });
+    entity_manager.remove(&managed);
+
+    // Drive the entry's own flush rather than `EntityManager::flush`, which opens
+    // a transaction a disconnected handle cannot. This is the branch under test,
+    // and reaching it at all proves no DELETE was attempted.
+    use crate::entity_manager::managed::ManagedOps;
+    managed.entry.clone().flush(&entity_manager).await?;
+
+    assert!(
+        entity_manager
+            .get_managed_by_key::<EntityManagerModTestWidget>("77")
+            .is_none(),
+        "a removed entity must not stay in the identity map"
+    );
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn registering_two_unsaved_entities_keeps_them_distinct() {
+    let entity_manager = Arc::new(EntityManager::new(Arc::new(Database::disconnected())));
+
+    // Both have the default primary key, which `tide_pk_key` renders as "0".
+    // Filing them under it made the second collide with the first and get the
+    // first handed back — silently dropping one child and inserting the other
+    // twice.
+    let first = entity_manager
+        .register(EntityManagerModTestUser {
+            id: 0,
+            name: "first".to_string(),
+        })
+        .await;
+    let second = entity_manager
+        .register(EntityManagerModTestUser {
+            id: 0,
+            name: "second".to_string(),
+        })
+        .await;
+
+    assert_eq!(first.name, "first");
+    assert_eq!(
+        second.name, "second",
+        "an unsaved entity has no identity to share, so it must not alias another"
+    );
+}