feat(server): add CRUD-aware interceptor system for Rust server (#116)

Enrich the server interceptor pipeline with CRUD context so
interceptors can distinguish entity insert from relation delete from
raw query — enabling rate limiting, tenant filtering, and CRUD-aware
audit logging at the HTTP layer.

- CrudInfo struct with operation/type_name/type_kind/attribute_names/iid
- CrudInterceptor convenience trait + CrudInterceptorAdapter bridge
- RequestContext and QueryInput carry crud_info through the pipeline
- All 8 CRUD handlers populate CrudInfo; non-CRUD uses Default
- PipelineBuilder::with_skip_validation() for tests needing schema without validation
- 100% MC/DC coverage on all changed files (regions/functions/lines)
  - crud_interceptor.rs branches at 87.5% (1 missed: generic monomorphization artifact)
- 295 tests total (25 new)

Author: ds1sqe

CHANGELOG.md

@@ -2,54 +2,103 @@
 
 All notable changes to TypeBridge will be documented in this file.
 
+## [Unreleased]
+
+### New Features
+
+#### 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`
+  - Compiler: Generates `put\n<statements>;` TypeQL output
+  - Validation: Reuses Insert validation rules (`Clause::Insert | Clause::Put`)
+  - Full roundtrip support (parse → AST → compile → parse)
+
+### 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 `crud_builder` benchmark** and `criterion` dev-dependency
+- **Server now has 4 endpoints**: `POST /query`, `POST /query/validate`, `GET /health`, `GET /schema`
+
 ## [1.4.0] - 2026-02-20
 
+### Highlights
+
+- 5 new Rust crates: `core-lib`, `orm`, `orm-derive`, `server`, and `python` (PyO3 bindings)
+- Up to **40x faster validation** and **2.5x faster query compilation** via the Rust backend
+- Async Rust ORM with derive macros, chainable queries, and batch operations
+- Query-intercepting proxy server with REST endpoints
+- MkDocs Material documentation site
+
 ### New Features
 
-#### Rust Core Integration (PRs #95, #101–#107)
+#### Rust Core — `type-bridge-core-lib` (PRs #95, #101-#108)
 - **TypeQL schema parser** with inheritance resolution and PyO3 bindings
 - **TypeQL query parser** with bidirectional AST roundtrip
-- **Schema-aware query validation** with PyO3 bindings
+- **Schema-aware query validation** with statement and pattern validators
 - **Rust-backed value coercion** and `format_value`
 - **Custom validation rules** with portable JSON DSL
 - **Wired Rust core into Python** compiler and validation pipeline
 
-#### Rust ORM — `type-bridge-orm` (PR #114)
-- **Async Rust ORM** with entity CRUD and mock-testable session layer
-- **Derive macros** — `TypeBridgeEntity`, `TypeBridgeAttribute`, `TypeBridgeRelation`
-- **Relation support** with update/put operations
+#### Async Rust ORM — `type-bridge-orm` (PR #114)
+- **Async ORM** with entity CRUD and mock-testable session layer
+- **Derive macros** — `#[derive(TypeBridgeEntity)]`, `#[derive(TypeBridgeRelation)]`, `#[derive(TypeBridgeAttribute)]`
 - **Chainable query builders** with expression filtering and aggregation
 - **Schema management** — registration, generation, diff, and sync
-- **Abstract types, inheritance, and code generator**
+- **Abstract types** with inheritance and code generation
 - **Batch operations** — `insert_many`, `delete_many`, `update_many`
 - **`FieldRef<A>`** for type-safe query field references
-- **`include_schema!` proc-macro** for compile-time TQL codegen
+- **`include_schema!`** proc-macro for compile-time TQL codegen
 - **Schema introspection** from live TypeDB database
 - **Group-by queries** with `GroupByResult`
 - **Role player field access** for relation query filtering
-- **Expression helpers** — `in_range`, `startswith`, `endswith`
-- **Connection pooling** with `Database::into_shared`
+- **Expression helpers** — `in_range()`, `startswith()`, `endswith()`
+- **Connection pooling** with `Database::into_shared()`
 - **Serde support** on all ORM model types
-- **Structured tracing spans** on all public methods
+- **Structured tracing** spans on all public methods
 
-#### Query Intercept Proxy Server — `type-bridge-server` (PR #109)
+#### Query Intercept Proxy — `type-bridge-server` (PR #109)
 - **REST CRUD endpoints** with schema-aware query building
-- **`CrudQueryBuilder` PyO3 class** for TypeQL generation
-- **Extensible library/framework architecture**
-- **207 tests** with 100% MC/DC coverage and CI codecov integration
+- **`CrudQueryBuilder` PyO3 class** for TypeQL generation from Python
+- **Extensible library/framework** — pluggable `QueryExecutor`, `Interceptor`, `SchemaSource`
+- **207 tests** with 100% MC/DC coverage
 
-### Improvements
+### Performance: Python vs Rust
+
+#### Validation
+
+| Operation | Python | Rust | Speedup |
+|-----------|--------|------|---------|
+| Single type name | 1.89 us | 354.75 ns | **5.3x** |
+| Long name (100+ chars) | 24.90 us | 620.52 ns | **40.1x** |
+| Batch 1,000 names | 5.32 ms | 266.80 us | **19.9x** |
+| Batch 5,000 names | 28.02 ms | 1.33 ms | **21.1x** |
+
+#### Query Compilation (via serde bridge)
+
+| Operation | Python | Rust | Speedup |
+|-----------|--------|------|---------|
+| Standalone update | 93.28 us | 37.82 us | **2.5x** |
+| Large batch (200 clauses) | 2.26 ms | 1.07 ms | **2.1x** |
+| Heavy insert (100x6) | 1.71 ms | 896.19 us | **1.9x** |
+
+### Documentation & CI
 
-#### Documentation & CI
 - **MkDocs + Material** documentation site with auto-generated API reference (PR #98)
-- **Rust crate CI** and multi-platform wheel builds (PR #95)
-- **Comprehensive benchmark suite** with TOML storage and diff support (PR #103)
-- Full documentation and metadata polish for Rust core
+- **Rust crate CI** with multi-platform wheel builds — Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64) (PR #95)
+- **Comprehensive benchmark suite** with TOML storage, comparison reports, and markdown generation (PR #103)
+- **Codecov integration** for Rust coverage tracking (PR #109)
 
 ### Bug Fixes
 
 - Resolve Rust 1.93.0 clippy lint errors
 - Pin Python 3.13 for Rust CI jobs and fix coverage script
+- Add version specifiers to inter-crate path dependencies for crates.io publishing
+- Make release workflow idempotent (skip already-published packages)
 
 ## [1.3.0] - 2026-02-09
 

type-bridge-core/Cargo.lock

@@ -235,6 +235,11 @@ pub enum Clause {
     MatchLet(Vec<LetAssignment>),
     /// An insert clause containing statements that create new data.
     Insert(Vec<Statement>),
+    /// A put clause containing statements for idempotent insert (upsert).
+    ///
+    /// Semantics: insert if not exists, otherwise return the existing match.
+    /// Uses the same statement syntax as `Insert`.
+    Put(Vec<Statement>),
     /// A delete clause containing statements that remove existing data.
     Delete(Vec<Statement>),
     /// An update clause containing statements that modify existing data.

type-bridge-core/crates/core/src/ast.rs

@@ -43,6 +43,13 @@ impl QueryCompiler {
                     .join(";\n");
                 format!("insert\n{};", s_str)
             }
+            Clause::Put(statements) => {
+                let s_str = statements.iter()
+                    .map(|s| self.compile_statement(s))
+                    .collect::<Vec<_>>()
+                    .join(";\n");
+                format!("put\n{};", s_str)
+            }
             Clause::Delete(statements) => {
                 let s_str = statements.iter()
                     .map(|s| self.compile_statement(s))
@@ -660,6 +667,16 @@ mod tests {
         assert_eq!(c.compile_clause(&clause), "insert\n$p has name \"Alice\";");
     }
 
+    #[test]
+    fn test_clause_put() {
+        let c = compiler();
+        let clause = Clause::Put(vec![
+            Statement::Isa { variable: "$p".into(), type_name: "person".into() },
+            Statement::Has { subject_var: "$p".into(), attr_name: "name".into(), value: lit(json!("Alice"), "string") },
+        ]);
+        assert_eq!(c.compile_clause(&clause), "put\n$p isa person;\n$p has name \"Alice\";");
+    }
+
     #[test]
     fn test_clause_delete() {
         let c = compiler();
@@ -856,6 +873,18 @@ mod tests {
         assert!(result.contains("insert\n"));
     }
 
+    #[test]
+    fn test_multi_clause_match_put() {
+        let c = compiler();
+        let clauses = vec![
+            Clause::Match(vec![Pattern::Entity { variable: "$p".into(), type_name: "person".into(), constraints: vec![], is_strict: false }]),
+            Clause::Put(vec![Statement::Has { subject_var: "$p".into(), attr_name: "age".into(), value: lit(json!(30), "long") }]),
+        ];
+        let result = c.compile(&clauses);
+        assert!(result.starts_with("match\n"));
+        assert!(result.contains("put\n"));
+    }
+
     #[test]
     fn test_multi_clause_match_delete() {
         let c = compiler();
@@ -968,6 +997,16 @@ mod tests {
         roundtrip("insert\n$r isa employment, links (employee: $p, employer: $c);");
     }
 
+    #[test]
+    fn test_roundtrip_put() {
+        roundtrip("put\n$p isa person;\n$p has name \"Alice\";");
+    }
+
+    #[test]
+    fn test_roundtrip_match_put() {
+        roundtrip("match $p isa person, has name \"Alice\";\nput\n$p has age 30;");
+    }
+
     #[test]
     fn test_roundtrip_match_delete() {
         roundtrip("match $p isa person, has name \"Alice\";\ndelete $p;");

type-bridge-core/crates/core/src/compiler.rs

@@ -590,6 +590,7 @@ fn parse_patterns(input: &mut &str) -> PResult<Vec<Pattern>> {
         ws_comments(input);
         if input.is_empty()
             || input.starts_with("insert")
+            || input.starts_with("put")
             || input.starts_with("delete")
             || input.starts_with("update")
             || input.starts_with("fetch")
@@ -897,6 +898,7 @@ fn parse_statements(input: &mut &str, ctx: StmtContext) -> PResult<Vec<Statement
         if input.is_empty()
             || input.starts_with("match")
             || input.starts_with("insert")
+            || input.starts_with("put")
             || input.starts_with("delete")
             || input.starts_with("update")
             || input.starts_with("fetch")
@@ -1202,6 +1204,7 @@ fn parse_clause(input: &mut &str) -> PResult<Clause> {
     alt((
         parse_match_clause,
         parse_insert_clause,
+        parse_put_clause,
         parse_delete_clause,
         parse_update_clause,
         parse_fetch_clause,
@@ -1259,6 +1262,14 @@ fn parse_insert_clause(input: &mut &str) -> PResult<Clause> {
     Ok(Clause::Insert(stmts))
 }
 
+/// Parse a put clause: `put\n<statements>;`.
+fn parse_put_clause(input: &mut &str) -> PResult<Clause> {
+    literal("put").parse_next(input)?;
+    ws_comments(input);
+    let stmts = parse_statements(input, StmtContext::Insert)?;
+    Ok(Clause::Put(stmts))
+}
+
 /// Parse a delete clause: `delete\n<statements>;`.
 fn parse_delete_clause(input: &mut &str) -> PResult<Clause> {
     literal("delete").parse_next(input)?;
@@ -2129,6 +2140,28 @@ mod tests {
         }
     }
 
+    #[test]
+    fn test_parse_put_clause() {
+        let input = "put\n$p isa person;\n$p has name \"Alice\";";
+        let clauses = parse_typeql_query(input).unwrap();
+        assert_eq!(clauses.len(), 1);
+        match &clauses[0] {
+            Clause::Put(stmts) => {
+                assert_eq!(stmts.len(), 2);
+            }
+            _ => panic!("expected Put"),
+        }
+    }
+
+    #[test]
+    fn test_parse_match_put() {
+        let input = "match\n$p isa person;\nput\n$p has age 30;";
+        let clauses = parse_typeql_query(input).unwrap();
+        assert_eq!(clauses.len(), 2);
+        assert!(matches!(&clauses[0], Clause::Match(_)));
+        assert!(matches!(&clauses[1], Clause::Put(_)));
+    }
+
     #[test]
     fn test_parse_delete_clause() {
         let input = "delete\n$p;";

type-bridge-core/crates/core/src/query_parser.rs

@@ -654,7 +654,7 @@ impl ValidationEngine {
                     );
                 }
             }
-            Clause::Insert(stmts) => {
+            Clause::Insert(stmts) | Clause::Put(stmts) => {
                 self.validate_insert_stmts(stmts, schema, env, path, errors);
             }
             Clause::Delete(stmts) | Clause::Update(stmts) => {
@@ -2161,6 +2161,44 @@ mod schema_validation_tests {
         assert!(!result.is_valid);
         assert!(result.errors.iter().any(|e| e.code == "UNKNOWN_ATTRIBUTE_OWNERSHIP"));
     }
+
+    // -- Put clause validation (same semantics as Insert) --------------------
+
+    #[test]
+    fn test_put_valid() {
+        let engine = ValidationEngine::new();
+        let schema = build_test_schema();
+        let clauses = vec![Clause::Put(vec![
+            Statement::Isa { variable: "$p".into(), type_name: "person".into() },
+            Statement::Has { subject_var: "$p".into(), attr_name: "name".into(), value: Value::Literal(LiteralValue { value: json!("Alice"), value_type: "string".into() }) },
+        ])];
+        let result = engine.validate_query(&clauses, &schema);
+        assert!(result.is_valid);
+    }
+
+    #[test]
+    fn test_put_unknown_type() {
+        let engine = ValidationEngine::new();
+        let schema = build_test_schema();
+        let clauses = vec![Clause::Put(vec![
+            Statement::Isa { variable: "$x".into(), type_name: "spaceship".into() },
+        ])];
+        let result = engine.validate_query(&clauses, &schema);
+        assert!(!result.is_valid);
+        assert!(result.errors.iter().any(|e| e.code == "UNKNOWN_TYPE"));
+    }
+
+    #[test]
+    fn test_put_abstract_type() {
+        let engine = ValidationEngine::new();
+        let schema = build_test_schema();
+        let clauses = vec![Clause::Put(vec![
+            Statement::Isa { variable: "$a".into(), type_name: "animal".into() },
+        ])];
+        let result = engine.validate_query(&clauses, &schema);
+        assert!(!result.is_valid);
+        assert!(result.errors.iter().any(|e| e.code == "ABSTRACT_TYPE_INSTANTIATION"));
+    }
 }
 
 #[cfg(test)]
@@ -2398,4 +2436,5 @@ mod rule_tests {
         assert!(engine.validate_type_name("person", "entity").is_valid);
         assert!(!engine.validate_type_name("define", "entity").is_valid);
     }
+
 }

type-bridge-core/crates/core/src/validation.rs

@@ -45,11 +45,6 @@ tower-http = { version = "0.6", features = ["cors", "trace"], optional = true }
 tempfile = "3"
 http-body-util = "0.1"
 tower = { version = "0.5", features = ["util"] }
-criterion = { version = "0.5", features = ["html_reports"] }
-
-[[bench]]
-name = "crud_builder"
-harness = false
 
 [lints]
 workspace = true