chore(release): bump all versions to 1.4.1 and add lifecycle hooks docs

Bump Python packages (pyproject.toml, __init__.py) and all five Rust
crates from 1.4.0/1.4.0-rc0 to 1.4.1.

Docs:
- CHANGELOG: add [1.4.1] section covering lifecycle hooks (Python ORM,
  Rust ORM, Rust Server), Put clause, and server API simplification
- docs/guide/crud.md: add Lifecycle Hooks section with full API
  reference, examples (audit, validation, filtering, composition)
- docs/guide/index.md: add hooks to Quick Reference
- README.md: add Lifecycle Hooks to feature list
- CLAUDE.md: add hooks.py to project structure tree

Fix:
- Export missing CrudHook protocol from type_bridge top-level __all__

Author: ds1sqe

CHANGELOG.md

@@ -4,8 +4,33 @@ All notable changes to TypeBridge will be documented in this file.
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-03-03
+
 ### New Features
 
+#### Lifecycle Hook System (PR #118, closes #116)
+
+Three-layer hook system for reacting to CRUD lifecycle events (audit logging, validation, cache invalidation, async notifications).
+
+##### Python ORM — `type_bridge.crud.hooks`
+- **`CrudEvent` enum** — `PRE_INSERT`, `POST_INSERT`, `PRE_UPDATE`, `POST_UPDATE`, `PRE_DELETE`, `POST_DELETE`, `PRE_PUT`, `POST_PUT`
+- **`LifecycleHook` protocol** — implement only the methods you need (`pre_insert`, `post_delete`, etc.)
+- **`HookCancelled` exception** — raise in a pre-hook to abort the operation
+- **Per-manager registration** — `manager.add_hook(hook)` / `manager.remove_hook(hook)`, chainable
+- **`should_run(event, sender)`** filtering by event type or model class
+- Pre-hooks run in registration order; post-hooks run in reverse order (middleware unwinding)
+- Zero overhead when no hooks are registered
+
+##### Rust ORM — `type-bridge-orm`
+- **`LifecycleHook` trait** with `HookContext`, `PreHookResult` (Continue/Reject), and `HookRunner`
+- Integrated into `EntityManager` and `RelationManager` via `add_hook()`
+- Same semantics as the Python layer (registration-order pre-hooks, reverse-order post-hooks)
+
+##### Rust Server — `type-bridge-server`
+- **`CrudInfo`** on `RequestContext` — operation, type_name, type_kind, attribute_names, iid
+- **`CrudInterceptor` trait** with `on_crud_request` / `on_crud_response` and `should_intercept`
+- **`CrudInterceptorAdapter`** bridges `CrudInterceptor` into the existing `Interceptor` chain
+
 #### Put (Upsert) Clause — `type-bridge-core-lib`
 - **Added `Clause::Put(Vec<Statement>)` variant** for idempotent insert (upsert) operations
   - Parser: `parse_put_clause` with keyword lookahead in both `parse_patterns` and `parse_statements`
@@ -16,11 +41,7 @@ All notable changes to TypeBridge will be documented in this file.
 ### Refactoring
 
 #### Server API Simplification — `type-bridge-server`
-- **Removed CRUD convenience endpoints** (`/entities/*`, `/relations/*`) — the `/query` endpoint handles all AST-based queries
-- **Removed `/query/raw` endpoint** — raw TypeQL bypasses AST interception, defeating the middleware purpose
-- **Removed `CrudInfo` and `CrudInterceptor`** — built exclusively for CRUD handlers, dead weight without them
-- **Removed `execute_raw()` and `RawQueryInput`** from pipeline
-- **Removed `RawQueryRequest`** from transport types
+- **Removed standalone CRUD module** (`/entities/*`, `/relations/*` endpoints, `CrudQueryBuilder`, raw query support) — superseded by the interceptor-based design
 - **Removed `crud_builder` benchmark** and `criterion` dev-dependency
 - **Server now has 4 endpoints**: `POST /query`, `POST /query/validate`, `GET /health`, `GET /schema`
 

CLAUDE.md

@@ -84,6 +84,7 @@ type_bridge/
 │   ├── base.py           # Type variables (E, R)
 │   ├── utils.py          # Shared utilities (format_value, is_multi_value_attribute)
 │   ├── exceptions.py     # CRUD exceptions
+│   ├── hooks.py          # Lifecycle hooks (CrudEvent, HookCancelled, CrudHook, HookRunner)
 │   ├── entity/           # Entity CRUD operations
 │   │   ├── __init__.py   # Entity module exports
 │   │   ├── manager.py    # EntityManager class

README.md

@@ -25,6 +25,7 @@ A modern, Pythonic ORM for [TypeDB](https://github.com/typedb/typedb) with an At
 - **Data Validation**: Automatic type checking and coercion via Pydantic, including keyword validation
 - **JSON Support**: Seamless JSON serialization/deserialization
 - **CRUD Operations**: Full CRUD with fetching API (get, filter, all, update) for entities and relations
+- **Lifecycle Hooks**: Pre/post-operation hooks for audit logging, validation, cache invalidation, and async notifications
 - **Chainable Operations**: Filter, delete, and bulk update with method chaining and lambda functions
 - **Query Builder**: Pythonic interface for building TypeQL queries
 - **Multi-player Roles**: A single role can accept multiple entity types via `Role.multi(...)`

docs/guide/crud.md

@@ -1532,6 +1532,113 @@ def test_database_operations():
     mock_driver.databases.contains.assert_called_with("test_db")
 ```
 
+## Lifecycle Hooks
+
+Hooks let you react to CRUD events for cross-cutting concerns — audit logging, input validation, cache invalidation, auto-populating fields, and more.
+
+### Quick Example
+
+```python
+from type_bridge import CrudEvent, HookCancelled
+
+class AuditHook:
+    """Log every write operation."""
+
+    def post_insert(self, sender, instance):
+        print(f"[insert] {sender.__name__} iid={instance.iid}")
+
+    def post_update(self, sender, instance):
+        print(f"[update] {sender.__name__} iid={instance.iid}")
+
+    def post_delete(self, sender, instance):
+        print(f"[delete] {sender.__name__} iid={instance.iid}")
+
+
+manager = Person.manager(db)
+manager.add_hook(AuditHook())  # chainable — returns self
+```
+
+### Events
+
+The `CrudEvent` enum covers all eight lifecycle points:
+
+| Event | When it fires |
+|-------|---------------|
+| `PRE_INSERT` | Before inserting an entity/relation |
+| `POST_INSERT` | After a successful insert |
+| `PRE_UPDATE` | Before updating |
+| `POST_UPDATE` | After a successful update |
+| `PRE_DELETE` | Before deleting |
+| `POST_DELETE` | After a successful delete |
+| `PRE_PUT` | Before an idempotent put (upsert) |
+| `POST_PUT` | After a successful put |
+
+### Writing a Hook
+
+Hooks are **duck-typed** — implement only the methods you need. No base class required.
+
+```python
+class TimestampHook:
+    """Auto-populate created_at on insert."""
+
+    def pre_insert(self, sender, instance):
+        if hasattr(instance, "created_at") and instance.created_at is None:
+            instance.created_at = CreatedAt(datetime.now(timezone.utc))
+```
+
+### Cancelling Operations
+
+Raise `HookCancelled` in any pre-hook to abort the operation:
+
+```python
+class EmailDomainValidator:
+    def __init__(self, domain: str):
+        self.domain = domain
+
+    def pre_insert(self, sender, instance):
+        if hasattr(instance, "email"):
+            if not instance.email.value.endswith(f"@{self.domain}"):
+                raise HookCancelled(f"Email must end with @{self.domain}")
+
+    def pre_update(self, sender, instance):
+        self.pre_insert(sender, instance)  # same logic
+```
+
+### Filtering with `should_run`
+
+Implement `should_run(event, sender)` to restrict when a hook fires:
+
+```python
+class PersonOnlyHook:
+    def should_run(self, event, sender):
+        return sender.__name__ == "Person"
+
+    def post_insert(self, sender, instance):
+        print(f"New person: {instance}")
+```
+
+Without `should_run`, hooks run for every event on every model.
+
+### Registration and Composition
+
+```python
+manager = (
+    Person.manager(db)
+    .add_hook(TimestampHook())
+    .add_hook(EmailDomainValidator("company.com"))
+    .add_hook(AuditHook())
+)
+
+# Remove a hook later
+manager.remove_hook(audit_hook)
+```
+
+### Execution Order
+
+- **Pre-hooks** run in registration order. If any raises `HookCancelled`, the operation is aborted.
+- **Post-hooks** run in **reverse** registration order (middleware unwinding). Post-hook errors are logged but do not propagate.
+- **Zero overhead** when no hooks are registered — the runner short-circuits on an empty hook list.
+
 ## See Also
 
 - [Entities](entities.md) - Entity definition

docs/guide/index.md

@@ -58,6 +58,9 @@ alice = Person(name=Name("Alice"), age=Age(30))
 person_manager = Person.manager(db)
 person_manager.insert(alice)
 persons = person_manager.all()
+
+# 5. Add lifecycle hooks (optional)
+person_manager.add_hook(my_audit_hook)  # chainable
 ```
 
 ## Key Principles

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "type-bridge"
-version = "1.4.0"
+version = "1.4.1"
 description = "A modern, Pythonic ORM for TypeDB with an Attribute-based API"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -29,7 +29,7 @@ dependencies = [
     "lark>=1.1.9",
     "jinja2>=3.1.0",
     "typer>=0.15.0",
-    "type-bridge-core>=1.4.0",
+    "type-bridge-core>=1.4.1",
 ]
 
 [project.urls]

type-bridge-core/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "type-bridge-core-lib"
-version = "1.4.0"
+version = "1.4.1"
 edition = "2024"
 description = "TypeQL AST, schema parser, query compiler, and validation engine for type-bridge"
 license.workspace = true

type-bridge-core/crates/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "type-bridge-orm-derive"
-version = "1.4.0"
+version = "1.4.1"
 edition = "2024"
 description = "Derive macros for type-bridge-orm: TypeBridgeEntity, TypeBridgeAttribute, TypeBridgeRelation"
 license.workspace = true
@@ -14,7 +14,7 @@ proc-macro = true
 proc-macro2 = "1"
 quote = "1"
 syn = { version = "2", features = ["full", "extra-traits"] }
-type-bridge-core-lib = { path = "../core", version = "1.4.0" }
+type-bridge-core-lib = { path = "../core", version = "1.4.1" }
 
 [lints]
 workspace = true

type-bridge-core/crates/orm-derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "type-bridge-orm"
-version = "1.4.0"
+version = "1.4.1"
 edition = "2024"
 description = "Async ORM for TypeDB built on type-bridge-core-lib"
 license.workspace = true
@@ -21,13 +21,13 @@ typedb = ["dep:typedb-driver", "dep:futures"]
 derive = ["dep:type-bridge-orm-derive"]
 
 [dependencies]
-type-bridge-core-lib = { path = "../core", version = "1.4.0" }
+type-bridge-core-lib = { path = "../core", version = "1.4.1" }
 tokio = { version = "1", features = ["full"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 thiserror = "2"
 tracing = "0.1"
-type-bridge-orm-derive = { path = "../orm-derive", version = "1.4.0", optional = true }
+type-bridge-orm-derive = { path = "../orm-derive", version = "1.4.1", optional = true }
 
 # Optional: real TypeDB backend
 typedb-driver = { version = "3", optional = true }