version: 1.0.198

GEMINI.md

@@ -184,23 +184,27 @@ It evaluates as an **Independent Declarative Rules Engine**. Every `Case` block
     *   **`array`**: Homogeneous collection of items matching the `items` schema. Validation is homogeneous, so strictness checking does not apply. `"extensible"` is not applicable at the `array` level (tuple-like `prefixItems` are removed).
 *   **Inheritance Boundaries**: Strictness resets when crossing non-primitive `type` boundaries. A schema extending a strict parent remains strict unless it explicitly overrides with `"extensible": true`.
 
-### Immutable Properties (`"immutable": true`)
-To distinguish read-only hydrated endpoint references, computed properties, system-managed timestamps (`created_at`, `modified_at`), or audit fields from writable properties, JSPG introduces the universal `"immutable": true` schema keyword.
+### Immutable Properties (`"immutable": "always" | "external"`)
+To distinguish read-only hydrated endpoint references, computed properties, system-managed timestamps (`created_at`, `modified_at`), or audit fields from writable properties, JSPG supports the `"immutable"` property schema attribute, which takes string enum values (`"always"`, `"external"`, or omitted).
 
-*   **Developer Perspective**: Annotate properties in database schemas or trait definitions with `"immutable": true` when the property should be visible on reads (`jspg_query` / `.response`), but rejected or ignored on writes (`jspg_merge` / `.request`).
+*   **Enum Values**:
+    *   `"always"`: Property is permanently read-only across all boundaries (e.g. system-managed audit timestamps like `created_at`, `modified_at`, or computed fields).
+    *   `"external"`: Property is read-only from external client API requests (`.request` payloads), but can be populated or mutated by internal system operations.
+    *   Omitted: Property is fully writable.
+*   **Developer Perspective**: Annotate properties in database schemas or trait definitions with `"immutable": "always"` or `"immutable": "external"` when the property should be visible on reads (`jspg_query` / `.response`), but rejected or ignored on writes (`jspg_merge` / `.request`).
     ```json
     "properties": {
       "source": {
         "family": "lite.organization",
-        "immutable": true,
+        "immutable": "always",
         "description": "Read-only hydrated member entity summary on a membership edge."
       }
     }
     ```
 *   **Behavior Across Pillars**:
-    *   **Queryer (`jspg_query`)**: Hydrates and includes `immutable` properties in output read responses without restriction.
-    *   **Validator (`jspg_validate`)**: Context-aware. Returns `IMMUTABLE_PROPERTY_VIOLATION` if an `immutable` property is supplied in a write/request payload (schema IDs not ending in `.response`). Response schemas (`.response`) permit `immutable` fields.
-    *   **Merger (`jspg_merge`)**: Automatically skips `immutable` properties during object graph merging so client payloads can never mutate database columns or relationship edges.
+    *   **Queryer (`jspg_query`)**: Hydrates and includes `"immutable"` properties in output read responses without restriction.
+    *   **Validator (`jspg_validate`)**: Context-aware. Rejects specified `"immutable"` properties supplied in write/request payloads. Response schemas (`.response`) permit `"immutable"` fields.
+    *   **Merger (`jspg_merge`)**: Automatically skips `"immutable"` properties during object graph merging so client payloads can never mutate database columns or relationship edges.
 
 ### Format Leniency for Empty Strings
 To simplify frontend form validation, format validators specifically for `uuid`, `date-time`, and `email` explicitly allow empty strings (`""`), treating them as "present but unset".
@@ -339,7 +343,7 @@ The Merger provides an automated, high-performance graph synchronization engine.
 *   **Factual Creation Dependency Validation**: When `stage_entity` confirms `kind == "create"` via database lookup, `jspg_merge` evaluates `schema.obj.dependencies.get("created")`. If required creation fields are missing from `entity_fields`, `entity_objects`, or `entity_arrays`, `jspg_merge` halts and returns a structured `REQUIRED_FIELD_MISSING` `Drop`.
 *   **Structured Fail-Fast Error Propagation**: Internal merger operations return typed `Result<T, crate::drop::Error>` instances, allowing clean fail-fast `?` traversal and returning `Drop::with_errors(vec![err])` directly at the top-level API boundary on failure.
 *   **Prefix Foreign Key Matching**: Handles scenario where multiple relations point to the same table by using database Foreign Key constraint prefixes (`fk_`). For example, if a schema has `shipping_address` and `billing_address`, the merger resolves against `fk_shipping_address_entity` vs `fk_billing_address_entity` automatically to correctly route object properties.
-*   **Dynamic Deduplication & Lookups**: If a nested object is provided without an `id`, the Merger utilizes custom `lookup_fields` declared directly in the schema registry JSON comments. It validates at setup compile-time that a corresponding unique index exists in PostgreSQL for these fields. When merging, it dynamically builds query predicates for any satisfied `lookup_fields` sets in the entity's type hierarchy (checking child-to-parent hierarchies order-independently and combining satisfied keys with `UNION` queries) to discover the correct UUID to perform an UPDATE, preventing data duplication.
+*   **Dynamic Deduplication & Lookups (`lookup_fields` & `field_defaults`)**: If an entity payload is provided without an `id`, the Merger utilizes custom `lookup_fields` declared directly in the schema metadata (`COMMENT ON TABLE`). When searching for an existing database record (`fetch_entity`), it iterates candidate `lookup_fields` sets across the entity's type hierarchy. For any column in a lookup set that is omitted from the input payload, `fetch_entity` checks for a default value in `field_defaults` (populated from Postgres table column `DEFAULT` expressions during setup). If a default is found (e.g. `start_date: "0001-01-01T00:00:00+00:00"`), `fetch_entity` uses that default value to satisfy the lookup query predicate (`WHERE ... AND start_date = ...`). Crucially, `entity_fields` itself is **never mutated** with defaults during `merge_entity`, ensuring input payloads remain pure, preventing false `modified_at` updates or spurious change notifications, and allowing PostgreSQL to handle column default generation natively server-side on `INSERT`.
 *   **Hierarchical Table Inheritance**: The Punc system uses distributed table inheritance (e.g. `person` inherits `user` inherits `organization` inherits `entity`). The Merger splits the incoming JSON payload and performs atomic row updates across *all* relevant tables in the lineage map.
 *   **The Archive Paradigm**: Data is never deleted in the Punc system. The Merger securely enforces referential integrity by toggling the `archived` Boolean flag on the base `entity` table rather than issuing SQL `DELETE` commands.
 *   **Change Tracking & Reactivity**: The Merger diffs the incoming JSON against the existing database row (utilizing static, `DashMap`-cached `lookup` SELECT string templates). Every detected change is recorded into the `agreego.change` audit table, tracking the user mapping. It then natively uses `pg_notify` to broadcast a completely flat row-level diff out to the Go WebSocket server for O(1) routing.
@@ -370,6 +374,7 @@ The Queryer transforms Postgres into a pre-compiled Semantic Query Engine, desig
     *   **Multi-Table Branching**: If the Physical Table is a parent to other tables (e.g. `organization` has variations `["organization", "bot", "person"]`), the compiler generates a dynamic `CASE WHEN type = '...' THEN ...` query, expanding into sub-queries for each variation. To ensure safe resolution, the compiler dynamically evaluates correlation boundaries: it attempts standard Relational Edge discovery first. If no explicit relational edge exists (indicating pure Table Inheritance rather than a standard foreign-key graph relationship), it safely invokes a **Table Parity Fallback**. This generates an explicit ID correlation constraint (`AND inner.id = outer.id`), perfectly binding the structural variations back to the parent row to eliminate Cartesian products.
     *   **Single-Table Bypass**: If the Physical Table is a leaf node with only one variation (e.g. `person` has variations `["person"]`), the compiler cleanly bypasses `CASE` generation and compiles a simple `SELECT` across the base table, as all schema extensions (e.g. `light.person`, `full.person`) are guaranteed to reside in the exact same physical row.
     *   **Polymorphic Relation Type Filtering**: When a relationship maps to a polymorphic target with variations, the Queryer compiles an `IN` clause containing all allowed table variations (e.g., `counterparty_type IN ('bot', 'organization', 'person')`) rather than matching the base type literal, ensuring all polymorphic types are loaded correctly.
+*   **Tenant Scoping & ReBAC Filtering**: When `jspg_query` compiles root-level or relationship-level entity queries, the generated SQL queries evaluate within the calling PostgreSQL transaction's session configuration (e.g. `auth.organization_ids`, `auth.roles`). The compiled queries seamlessly interact with PostgreSQL Row Level Security (RLS) policies on base tables (such as `agreego.entity`) and pre-materialized Zanzibar graph edges (`agreego.relationship`), ensuring multi-tenant isolation and $O(1)$ query evaluation without requiring manual WHERE scoping logic across every application punc.
 *   **Static Relation Constraints (Kind Constraints)**: When a relationship (such as a nested object or array) is defined with a schema that constrains a field value statically using a `const` or `enum` keyword (for example, `kind` constrained to `"cover"` in a `cover_attachment`), the Queryer automatically extracts these static assertions during AST compilation. It injects them directly as static filters into the SQL subquery's `WHERE` clause (e.g. `AND attachment.kind = 'cover'`), allowing developers to query pre-filtered subsets of related tables natively through the schema.
 *   **Proxy Schema Dereferencing / Resolution**: To support punc endpoints that return non-polymorphic table-backed shapes (using `type: "full.X"` proxy schemas at the root response level), the Queryer compiler automatically dereferences non-table schema pointers to their target schemas prior to checking the types. This allows the Queryer to correctly resolve the table relationship edges pre-compiled on the full schema, while avoiding polluting the database registry with relations on ad-hoc punc response schemas during setup.
 

fixtures/database.json

@@ -1027,16 +1027,31 @@
           "name": "user",
           "module": "test",
           "source": "test",
-          "hierarchy": ["user"],
-          "variations": ["user"],
-          "fields": ["id", "email"],
-          "lookup_fields": ["email"],
+          "hierarchy": [
+            "user"
+          ],
+          "variations": [
+            "user"
+          ],
+          "fields": [
+            "id",
+            "email"
+          ],
+          "lookup_fields": [
+            "email"
+          ],
           "schemas": {
             "user": {
               "type": "object",
               "properties": {
-                "id": { "type": "string", "format": "uuid" },
-                "email": { "type": "string", "format": "email" }
+                "id": {
+                  "type": "string",
+                  "format": "uuid"
+                },
+                "email": {
+                  "type": "string",
+                  "format": "email"
+                }
               }
             }
           }
@@ -1072,7 +1087,9 @@
       "indexes": [
         {
           "table": "user",
-          "columns": ["email"]
+          "columns": [
+            "email"
+          ]
         }
       ],
       "types": [
@@ -1082,16 +1099,31 @@
           "name": "user",
           "module": "test",
           "source": "test",
-          "hierarchy": ["user"],
-          "variations": ["user"],
-          "fields": ["id", "email"],
-          "lookup_fields": ["email"],
+          "hierarchy": [
+            "user"
+          ],
+          "variations": [
+            "user"
+          ],
+          "fields": [
+            "id",
+            "email"
+          ],
+          "lookup_fields": [
+            "email"
+          ],
           "schemas": {
             "user": {
               "type": "object",
               "properties": {
-                "id": { "type": "string", "format": "uuid" },
-                "email": { "type": "string", "format": "email" }
+                "id": {
+                  "type": "string",
+                  "format": "uuid"
+                },
+                "email": {
+                  "type": "string",
+                  "format": "email"
+                }
               }
             }
           }

fixtures/queryer.json

@@ -260,12 +260,9 @@
           },
           "lookup_fields": [],
           "null_fields": [],
-          "default_fields": [
-            "id",
-            "type",
-            "created_at",
-            "archived"
-          ],
+          "field_defaults": {
+            "archived": false
+          },
           "variations": [
             "bot",
             "organization",
@@ -1739,20 +1736,20 @@
               "    AND entity_1.created_at <= ($16 #>> '{}')::TIMESTAMPTZ",
               "    AND entity_1.created_at <> ($17 #>> '{}')::TIMESTAMPTZ",
               "    AND person_3.first_name ILIKE $18 #>> '{}'",
-              "    AND person_3.first_name > ($19 #>> '{)",
-              "      AND person_3.first_name >= ($20 #>> '{)",
-              "        AND person_3.first_name < ($21 #>> '{)",
-              "          AND person_3.first_name <= ($22 #>> '{)",
-              "            AND person_3.first_name NOT ILIKE $23 #>> '{}'",
-              "            AND person_3.first_name NOT IN (SELECT value FROM jsonb_array_elements_text(($24 #>> '{}')::jsonb))",
-              "            AND person_3.first_name IN (SELECT value FROM jsonb_array_elements_text(($25 #>> '{}')::jsonb))",
-              "            AND entity_1.id = ($26 #>> '{}')::UUID",
-              "            AND entity_1.id <> ($27 #>> '{}')::UUID",
-              "            AND entity_1.id NOT IN (SELECT value::UUID FROM jsonb_array_elements_text(($28 #>> '{}')::jsonb))",
-              "            AND entity_1.id IN (SELECT value::UUID FROM jsonb_array_elements_text(($29 #>> '{}')::jsonb))",
-              "            AND person_3.last_name ILIKE $30 #>> '{}'",
-              "            AND person_3.last_name NOT ILIKE $31 #>> '{}'",
-              "        ))))"
+              "    AND person_3.first_name > ($19 #>> '{}')",
+              "    AND person_3.first_name >= ($20 #>> '{}')",
+              "    AND person_3.first_name < ($21 #>> '{}')",
+              "    AND person_3.first_name <= ($22 #>> '{}')",
+              "    AND person_3.first_name NOT ILIKE $23 #>> '{}'",
+              "    AND person_3.first_name NOT IN (SELECT value FROM jsonb_array_elements_text(($24 #>> '{}')::jsonb))",
+              "    AND person_3.first_name IN (SELECT value FROM jsonb_array_elements_text(($25 #>> '{}')::jsonb))",
+              "    AND entity_1.id = ($26 #>> '{}')::UUID",
+              "    AND entity_1.id <> ($27 #>> '{}')::UUID",
+              "    AND entity_1.id NOT IN (SELECT value::UUID FROM jsonb_array_elements_text(($28 #>> '{}')::jsonb))",
+              "    AND entity_1.id IN (SELECT value::UUID FROM jsonb_array_elements_text(($29 #>> '{}')::jsonb))",
+              "    AND person_3.last_name ILIKE $30 #>> '{}'",
+              "    AND person_3.last_name NOT ILIKE $31 #>> '{}'",
+              "))))"
             ]
           ]
         }

src/database/executors/mock.rs

@@ -130,56 +130,69 @@ impl MockExecutor {
 #[cfg(test)]
 fn parse_and_match_mocks(sql: &str, mocks: &[Value]) -> Option<Vec<Value>> {
   let sql_upper = sql.to_uppercase();
-  if !sql_upper.starts_with("SELECT") {
+  if !sql_upper.starts_with("SELECT") && !sql_upper.starts_with("(SELECT") {
     return None;
   }
 
-  // 1. Extract table name
-  let table_regex = Regex::new(r#"(?i)\s+FROM\s+(?:[a-zA-Z_]\w*\.)?"?([a-zA-Z_]\w*)"?"#).ok()?;
-  let table = if let Some(caps) = table_regex.captures(sql) {
-    caps.get(1)?.as_str()
-  } else {
-    return None;
-  };
+  let union_regex = Regex::new(r"(?i)\s+UNION\s+").ok()?;
+  let queries: Vec<&str> = union_regex.split(sql).collect();
 
-  // 2. Extract WHERE conditions string
-  let mut where_clause = String::new();
-  if let Some(where_idx) = sql_upper.find(" WHERE ") {
-    let mut where_end = sql_upper.find(" ORDER BY ").unwrap_or(sql_upper.len());
-    if let Some(limit_idx) = sql_upper.find(" LIMIT ") {
-      if limit_idx < where_end {
-        where_end = limit_idx;
-      }
-    }
-    where_clause = sql[where_idx + 7..where_end].to_string();
-  }
-
-  // 3. Find matching mocks
   let mut matches = Vec::new();
   let or_regex = Regex::new(r"(?i)\s+OR\s+").ok()?;
   let and_regex = Regex::new(r"(?i)\s+AND\s+").ok()?;
 
   for mock in mocks {
-    if let Some(mock_obj) = mock.as_object() {
-      if let Some(t) = mock_obj.get("type") {
-        if t.as_str() != Some(table) {
-          continue;
-        }
-      }
+    let mock_obj = match mock.as_object() {
+      Some(obj) => obj,
+      None => continue,
+    };
 
-      if where_clause.is_empty() {
-        matches.push(mock.clone());
+    let mock_type = mock_obj.get("type").and_then(|v| v.as_str()).unwrap_or("");
+
+    let mut mock_matched = false;
+
+    for query in &queries {
+      let q_upper = query.to_uppercase();
+
+      // Check if mock type matches the table or any joined tables in this query
+      let table_regex = Regex::new(r#"(?i)\s+(?:FROM|JOIN)\s+(?:[a-zA-Z_]\w*\.)?"?([a-zA-Z_]\w*)"?"#).ok()?;
+      let tables: Vec<String> = table_regex
+        .captures_iter(query)
+        .filter_map(|c| c.get(1).map(|m| m.as_str().to_string()))
+        .collect();
+
+      if !mock_type.is_empty() && !tables.is_empty() && !tables.iter().any(|t| t == mock_type) {
         continue;
       }
 
-      let or_parts = or_regex.split(&where_clause);
-      let mut any_branch_matched = false;
+      // Extract WHERE clause
+      let mut where_clause = String::new();
+      if let Some(where_idx) = q_upper.find(" WHERE ") {
+        let mut where_end = q_upper.find(" ORDER BY ").unwrap_or(q_upper.len());
+        if let Some(limit_idx) = q_upper.find(" LIMIT ") {
+          if limit_idx < where_end {
+            where_end = limit_idx;
+          }
+        }
+        where_clause = query[where_idx + 7..where_end].trim_end_matches(')').to_string();
+      }
 
+      if where_clause.is_empty() {
+        mock_matched = true;
+        break;
+      }
+
+      let or_parts = or_regex.split(&where_clause);
       for or_part in or_parts {
         let branch_str = or_part.replace('(', "").replace(')', "");
         let mut branch_matches = true;
 
         for part in and_regex.split(&branch_str) {
+          let part = part.trim();
+          if part.is_empty() {
+            continue;
+          }
+
           if let Some(eq_idx) = part.find('=') {
             let left = part[..eq_idx]
               .trim()
@@ -193,7 +206,7 @@ fn parse_and_match_mocks(sql: &str, mocks: &[Value]) -> Option<Vec<Value>> {
               Some(Value::String(s)) => s.clone(),
               Some(Value::Number(n)) => n.to_string(),
               Some(Value::Bool(b)) => b.to_string(),
-              Some(Value::Null) => "null".to_string(),
+              Some(Value::Null) | None => "null".to_string(),
               _ => "".to_string(),
             };
             if mock_val_str != right {
@@ -201,19 +214,21 @@ fn parse_and_match_mocks(sql: &str, mocks: &[Value]) -> Option<Vec<Value>> {
               break;
             }
           } else if part.to_uppercase().contains(" IS NULL") {
-            let left = part[..part.to_uppercase().find(" IS NULL").unwrap()]
+            let is_null_idx = part.to_uppercase().find(" IS NULL").unwrap();
+            let left = part[..is_null_idx]
               .trim()
               .split('.')
               .last()
               .unwrap_or("")
               .trim_matches('"');
 
-            let mock_val_str = match mock_obj.get(left) {
-              Some(Value::Null) => "null".to_string(),
-              _ => "".to_string(),
+            let is_null_val = match mock_obj.get(left) {
+              Some(Value::Null) | None => true,
+              Some(Value::String(s)) if s.is_empty() => true,
+              _ => false,
             };
 
-            if mock_val_str != "null" {
+            if !is_null_val {
               branch_matches = false;
               break;
             }
@@ -221,15 +236,19 @@ fn parse_and_match_mocks(sql: &str, mocks: &[Value]) -> Option<Vec<Value>> {
         }
 
         if branch_matches {
-          any_branch_matched = true;
+          mock_matched = true;
           break;
         }
       }
 
-      if any_branch_matched {
-        matches.push(mock.clone());
+      if mock_matched {
+        break;
       }
     }
+
+    if mock_matched {
+      matches.push(mock.clone());
+    }
   }
 
   Some(matches)

src/database/executors/pgrx.rs

@@ -77,8 +77,8 @@ impl DatabaseExecutor for SpiExecutor {
 
     pgrx::debug1!("JSPG_SQL: {}", sql);
     self.transact(|| {
-      Spi::connect(|client| {
-        match client.select(sql, Some(args_with_oid.len() as i64), &args_with_oid) {
+      Spi::connect_mut(|client| {
+        match client.update(sql, Some(args_with_oid.len() as i64), &args_with_oid) {
           Ok(tup_table) => {
             let mut results = Vec::new();
             for row in tup_table {

src/database/type.rs

@@ -5,6 +5,14 @@ use serde::{Deserialize, Serialize};
 use std::sync::Arc;
 use serde_json::Value;
 
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct Roles {
+  #[serde(default, skip_serializing_if = "Vec::is_empty")]
+  pub read: Vec<String>,
+  #[serde(default, skip_serializing_if = "Vec::is_empty")]
+  pub write: Vec<String>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 #[serde(default)]
 pub struct Type {
@@ -36,8 +44,10 @@ pub struct Type {
   #[serde(default)]
   pub null_fields: Vec<String>,
   #[serde(default)]
-  pub default_fields: Vec<String>,
+  pub field_defaults: IndexMap<String, Value>,
   pub field_types: Option<Value>,
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub roles: Option<Roles>,
   #[serde(default)]
   pub schemas: IndexMap<String, Arc<Schema>>,
 }

src/lib.rs

@@ -57,7 +57,7 @@ pub fn jspg_setup(database: Json) -> Json {
   Json(serde_json::to_value(drop).unwrap())
 }
 
-#[cfg_attr(not(test), pg_extern)]
+#[cfg_attr(not(test), pg_extern(volatile))]
 pub fn jspg_merge(schema_id: &str, data: JsonB) -> JsonB {
   // Try to acquire a read lock to get a clone of the Engine Arc
   let engine_opt = {
@@ -74,7 +74,7 @@ pub fn jspg_merge(schema_id: &str, data: JsonB) -> JsonB {
   }
 }
 
-#[cfg_attr(not(test), pg_extern)]
+#[cfg_attr(not(test), pg_extern(volatile))]
 pub fn jspg_merge_ordered(schema_id: &str, data: Json) -> Json {
   let engine_opt = {
     let lock = GLOBAL_JSPG.read().unwrap();

src/merger/mod.rs

@@ -6,8 +6,8 @@ pub mod cache;
 use crate::database::Database;
 use crate::database::r#type::Type;
 use crate::drop::{Drop, Error, ErrorDetails};
-use serde_json::Value;
 use indexmap::IndexMap;
+use serde_json::Value;
 use std::sync::Arc;
 
 pub struct Merger {
@@ -31,9 +31,10 @@ impl Merger {
       None => {
         return Drop::with_errors(vec![Error {
           code: "SCHEMA_NOT_FOUND".to_string(),
-          values: Some(IndexMap::from([
-            ("schema".to_string(), schema_id.to_string()),
-          ])),
+          values: Some(IndexMap::from([(
+            "schema".to_string(),
+            schema_id.to_string(),
+          )])),
           details: ErrorDetails {
             path: None,
             cause: None,
@@ -56,9 +57,7 @@ impl Merger {
       if let Err(e) = self.db.execute(&notify_sql, None) {
         return Drop::with_errors(vec![Error {
           code: "MERGE_FAILED".to_string(),
-          values: Some(IndexMap::from([
-            ("error".to_string(), e.clone()),
-          ])),
+          values: Some(IndexMap::from([("error".to_string(), e.clone())])),
           details: ErrorDetails {
             path: None,
             cause: Some(e),
@@ -121,9 +120,15 @@ impl Merger {
                   } else {
                     return Err(Error {
                       code: "TARGET_SCHEMA_NOT_FOUND".to_string(),
-                      values: Some(IndexMap::from([("target_id".to_string(), target_id.clone())])),
+                      values: Some(IndexMap::from([(
+                        "target_id".to_string(),
+                        target_id.clone(),
+                      )])),
                       details: ErrorDetails {
-                        cause: Some(format!("Polymorphic mapped target '{}' not found in database registry", target_id)),
+                        cause: Some(format!(
+                          "Polymorphic mapped target '{}' not found in database registry",
+                          target_id
+                        )),
                         ..Default::default()
                       },
                     });
@@ -141,7 +146,10 @@ impl Merger {
                       code: "ONE_OF_INDEX_NOT_FOUND".to_string(),
                       values: Some(IndexMap::from([("index".to_string(), idx.to_string())])),
                       details: ErrorDetails {
-                        cause: Some(format!("Polymorphic index target '{}' not found in local oneOf array", idx)),
+                        cause: Some(format!(
+                          "Polymorphic index target '{}' not found in local oneOf array",
+                          idx
+                        )),
                         ..Default::default()
                       },
                     });
@@ -164,7 +172,10 @@ impl Merger {
                     ("value".to_string(), v.to_string()),
                   ])),
                   details: ErrorDetails {
-                    cause: Some(format!("Polymorphic discriminator {}='{}' matched no compiled options", disc, v)),
+                    cause: Some(format!(
+                      "Polymorphic discriminator {}='{}' matched no compiled options",
+                      disc, v
+                    )),
                     ..Default::default()
                   },
                 });
@@ -172,9 +183,15 @@ impl Merger {
             } else {
               return Err(Error {
                 code: "MISSING_DISCRIMINATOR".to_string(),
-                values: Some(IndexMap::from([("discriminator".to_string(), disc.to_string())])),
+                values: Some(IndexMap::from([(
+                  "discriminator".to_string(),
+                  disc.to_string(),
+                )])),
                 details: ErrorDetails {
-                  cause: Some(format!("Polymorphic merging failed: missing required discriminator '{}'", disc)),
+                  cause: Some(format!(
+                    "Polymorphic merging failed: missing required discriminator '{}'",
+                    disc
+                  )),
                   ..Default::default()
                 },
               });
@@ -281,8 +298,6 @@ impl Merger {
     let mut entity_objects = std::collections::BTreeMap::new();
     let mut entity_arrays = std::collections::BTreeMap::new();
 
-    let is_external = self.db.executor.punc_external().unwrap_or(false);
-
     for (k, v) in obj {
       // Always retain system and unmapped core fields natively implicitly mapped to the Postgres tables
       if k == "id" || k == "type" || k == "created" {
@@ -291,12 +306,6 @@ impl Merger {
       }
 
       if let Some(prop_schema) = compiled_props.get(&k) {
-        if prop_schema.is_immutable(is_external) {
-          continue;
-        }
-
-
-
         let mut is_edge = false;
         if let Some(edges) = schema.obj.compiled_edges.get() {
           if edges.contains_key(&k) {
@@ -326,6 +335,8 @@ impl Merger {
       }
     }
 
+
+
     let mut current_org_id = None;
     if let Some(compiled_props) = schema.obj.compiled_properties.get() {
       if let Some(org_schema) = compiled_props.get("organization_id") {
@@ -373,7 +384,10 @@ impl Merger {
         if let Some(deps) = &schema.obj.dependencies {
           if let Some(crate::database::object::Dependency::Props(req_props)) = deps.get("created") {
             for req in req_props {
-              if !entity_fields.contains_key(req) && !entity_objects.contains_key(req) && !entity_arrays.contains_key(req) {
+              if !entity_fields.contains_key(req)
+                && !entity_objects.contains_key(req)
+                && !entity_arrays.contains_key(req)
+              {
                 return Err(Error {
                   code: "REQUIRED_FIELD_MISSING".to_string(),
                   values: Some(IndexMap::from([
@@ -382,7 +396,10 @@ impl Merger {
                   ])),
                   details: ErrorDetails {
                     path: Some(req.to_string()),
-                    cause: Some(format!("Missing required creation field '{}' for entity {}", req, type_name)),
+                    cause: Some(format!(
+                      "Missing required creation field '{}' for entity {}",
+                      req, type_name
+                    )),
                     ..Default::default()
                   },
                 });
@@ -493,7 +510,7 @@ impl Merger {
       entity_change_kind.as_deref().unwrap_or(""),
       &type_name,
       type_def,
-      &entity_fields,
+      &mut entity_fields,
       entity_fetched.as_ref(),
     )?;
 
@@ -745,21 +762,34 @@ impl Merger {
       if let Some(parent_type) = self.db.types.get(parent_type_name) {
         if !parent_type.lookup_fields.is_empty() {
           let mut lookup_complete = true;
+          let mut has_provided_fields = false;
           for column in &parent_type.lookup_fields {
-            match entity_fields.get(column) {
+            let is_nullable = parent_type.null_fields.contains(column);
+            let val = entity_fields.get(column).or_else(|| {
+              parent_type.field_defaults.get(column)
+            });
+            match val {
               Some(Value::Null) | None => {
-                lookup_complete = false;
-                break;
+                if !is_nullable {
+                  lookup_complete = false;
+                  break;
+                }
               }
               Some(Value::String(s)) if s.is_empty() => {
-                lookup_complete = false;
-                break;
+                if !is_nullable {
+                  lookup_complete = false;
+                  break;
+                }
+              }
+              _ => {
+                if entity_fields.contains_key(column) {
+                  has_provided_fields = true;
+                }
               }
-              _ => {}
             }
           }
-          if lookup_complete {
-            lookup_satisfied_keys.push(&parent_type.lookup_fields);
+          if lookup_complete && has_provided_fields {
+            lookup_satisfied_keys.push((&parent_type.lookup_fields, parent_type));
           }
         }
       }
@@ -772,7 +802,7 @@ impl Merger {
     let fetch_sql_template = if let Some(cached) = self.cache.get(entity_type_name) {
       cached
     } else {
-      let mut select_list = String::from("to_jsonb(t1.*)");
+      let mut select_list = String::from("COALESCE(to_jsonb(t1.*), '{}')");
       let mut join_clauses = format!("FROM agreego.\"{}\" t1", entity_type.hierarchy[0]);
 
       for (i, table_name) in entity_type.hierarchy.iter().enumerate().skip(1) {
@@ -781,7 +811,7 @@ impl Merger {
           " LEFT JOIN agreego.\"{}\" {} ON {}.id = t1.id",
           table_name, t_alias, t_alias
         ));
-        select_list.push_str(&format!(" || to_jsonb({}.*)", t_alias));
+        select_list.push_str(&format!(" || COALESCE(to_jsonb({}.*), '{{}}')", t_alias));
       }
 
       let template = format!("SELECT {} {}", select_list, join_clauses);
@@ -797,14 +827,24 @@ impl Merger {
       where_parts.push(format!("t1.id = {}", Self::quote_literal(id)));
     }
 
-    for lookup_fields in lookup_satisfied_keys {
+    for (lookup_fields, parent_type) in lookup_satisfied_keys {
+      let t_alias = entity_type
+        .hierarchy
+        .iter()
+        .position(|name| name == &parent_type.name)
+        .map(|idx| format!("t{}", idx + 1))
+        .unwrap_or_else(|| "t1".to_string());
+
       let mut lookup_predicates = Vec::new();
       for column in lookup_fields {
-        let val = entity_fields.get(column).unwrap_or(&Value::Null);
-        if column == "type" {
-          lookup_predicates.push(format!("t1.\"{}\" = {}", column, Self::quote_literal(val)));
+        let val = entity_fields
+          .get(column)
+          .or_else(|| parent_type.field_defaults.get(column))
+          .unwrap_or(&Value::Null);
+        if val.is_null() || val.as_str() == Some("") {
+          lookup_predicates.push(format!("{}.\"{}\" IS NULL", t_alias, column));
         } else {
-          lookup_predicates.push(format!("\"{}\" = {}", column, Self::quote_literal(val)));
+          lookup_predicates.push(format!("{}.\"{}\" = {}", t_alias, column, Self::quote_literal(val)));
         }
       }
       where_parts.push(format!("({})", lookup_predicates.join(" AND ")));
@@ -829,9 +869,15 @@ impl Merger {
         if table.len() > 1 {
           Err(Error {
             code: "TOO_MANY_LOOKUP_ROWS".to_string(),
-            values: Some(IndexMap::from([("entity_type".to_string(), entity_type_name.to_string())])),
+            values: Some(IndexMap::from([(
+              "entity_type".to_string(),
+              entity_type_name.to_string(),
+            )])),
             details: ErrorDetails {
-              cause: Some(format!("Lookup for {} found too many existing rows", entity_type_name)),
+              cause: Some(format!(
+                "Lookup for {} found too many existing rows",
+                entity_type_name
+              )),
               ..Default::default()
             },
           })
@@ -878,7 +924,7 @@ impl Merger {
     change_kind: &str,
     entity_type_name: &str,
     entity_type: &crate::database::r#type::Type,
-    entity_fields: &serde_json::Map<String, Value>,
+    entity_fields: &mut serde_json::Map<String, Value>,
     _entity_fetched: Option<&serde_json::Map<String, Value>>,
   ) -> Result<(), Error> {
     if change_kind.is_empty() {
@@ -886,7 +932,7 @@ impl Merger {
     }
 
     let id_str = match entity_fields.get("id").and_then(|v| v.as_str()) {
-      Some(id) => id,
+      Some(id) => id.to_string(),
       None => {
         return Err(Error {
           code: "MISSING_ENTITY_ID".to_string(),
@@ -904,9 +950,15 @@ impl Merger {
       _ => {
         return Err(Error {
           code: "MISSING_GROUPED_FIELDS".to_string(),
-          values: Some(IndexMap::from([("type".to_string(), entity_type_name.to_string())])),
+          values: Some(IndexMap::from([(
+            "type".to_string(),
+            entity_type_name.to_string(),
+          )])),
           details: ErrorDetails {
-            cause: Some(format!("Grouped fields missing for type {}", entity_type_name)),
+            cause: Some(format!(
+              "Grouped fields missing for type {}",
+              entity_type_name
+            )),
             ..Default::default()
           },
         });
@@ -923,7 +975,7 @@ impl Merger {
       };
 
       let mut entity_pairs = serde_json::Map::new();
-      for (k, v) in entity_fields {
+      for (k, v) in entity_fields.iter() {
         if table_fields.contains(k) {
           entity_pairs.insert(k.clone(), v.clone());
         }
@@ -957,20 +1009,33 @@ impl Merger {
         }
 
         let sql = format!(
-          "INSERT INTO agreego.\"{}\" ({}) VALUES ({})",
+          "INSERT INTO agreego.\"{}\" ({}) VALUES ({}) RETURNING to_jsonb(\"{}\".*)",
           table_name,
           columns.join(", "),
-          values.join(", ")
+          values.join(", "),
+          table_name
         );
-        if let Err(e) = self.db.execute(&sql, None) {
-          return Err(Error {
-            code: "DATABASE_SPI_ERROR".to_string(),
-            values: Some(IndexMap::from([("error".to_string(), e.clone())])),
-            details: ErrorDetails {
-              cause: Some(e),
-              ..Default::default()
-            },
-          });
+        match self.db.query(&sql, None) {
+          Ok(Value::Array(rows)) => {
+            if let Some(Value::Object(row_map)) = rows.into_iter().next() {
+              for (k, v) in row_map {
+                if !v.is_null() {
+                  entity_fields.insert(k, v);
+                }
+              }
+            }
+          }
+          Err(e) => {
+            return Err(Error {
+              code: "DATABASE_SPI_ERROR".to_string(),
+              values: Some(IndexMap::from([("error".to_string(), e.clone())])),
+              details: ErrorDetails {
+                cause: Some(e),
+                ..Default::default()
+              },
+            });
+          }
+          _ => {}
         }
       } else if change_kind == "update" || change_kind == "delete" {
         entity_pairs.remove("id");
@@ -998,20 +1063,33 @@ impl Merger {
         }
 
         let sql = format!(
-          "UPDATE agreego.\"{}\" SET {} WHERE id = {}",
+          "UPDATE agreego.\"{}\" SET {} WHERE id = {} RETURNING to_jsonb(\"{}\".*)",
           table_name,
           set_clauses.join(", "),
-          Self::quote_literal(&Value::String(id_str.to_string()))
+          Self::quote_literal(&Value::String(id_str.to_string())),
+          table_name
         );
-        if let Err(e) = self.db.execute(&sql, None) {
-          return Err(Error {
-            code: "DATABASE_SPI_ERROR".to_string(),
-            values: Some(IndexMap::from([("error".to_string(), e.clone())])),
-            details: ErrorDetails {
-              cause: Some(e),
-              ..Default::default()
-            },
-          });
+        match self.db.query(&sql, None) {
+          Ok(Value::Array(rows)) => {
+            if let Some(Value::Object(row_map)) = rows.into_iter().next() {
+              for (k, v) in row_map {
+                if !v.is_null() {
+                  entity_fields.insert(k, v);
+                }
+              }
+            }
+          }
+          Err(e) => {
+            return Err(Error {
+              code: "DATABASE_SPI_ERROR".to_string(),
+              values: Some(IndexMap::from([("error".to_string(), e.clone())])),
+              details: ErrorDetails {
+                cause: Some(e),
+                ..Default::default()
+              },
+            });
+          }
+          _ => {}
         }
       }
     }

src/tests/formatter.rs

@@ -97,7 +97,14 @@ impl SqlFormatter {
             self.push_line("VALUES (");
             self.indent += 2;
             
-            let vals = if suffix.ends_with(")") { &suffix[..suffix.len() - 1] } else { suffix };
+            let (vals, returning_clause) = if let Some(ret_idx) = suffix.rfind(") RETURNING ") {
+                (&suffix[..ret_idx], Some(&suffix[ret_idx + 2..]))
+            } else if suffix.ends_with(")") {
+                (&suffix[..suffix.len() - 1], None)
+            } else {
+                (suffix, None)
+            };
+
             let mut val_tokens = Vec::new();
             let mut curr = String::new();
             let mut in_str = false;
@@ -119,7 +126,7 @@ impl SqlFormatter {
             for (i, val) in val_tokens.iter().enumerate() {
                 let comma = if i < val_tokens.len() - 1 { "," } else { "" };
                 
-                if val.starts_with("'{") && val.ends_with("}'") {
+                if val.starts_with("'{") && val.ends_with("}'") && val.len() > 4 {
                     let inner = &val[1..val.len() - 1];
                     // Unescape single quotes from SQL strings
                     let unescaped = inner.replace("''", "'");
@@ -146,6 +153,9 @@ impl SqlFormatter {
             }
             self.indent -= 2;
             self.push_line(")");
+            if let Some(ret) = returning_clause {
+                self.push_line(ret);
+            }
         } else {
             self.push_line(&s);
         }
@@ -168,10 +178,19 @@ impl SqlFormatter {
             self.indent -= 2;
             
             if let Some(w) = where_idx {
-                self.push_line("WHERE");
-                self.indent += 2;
-                self.push_line(&after_set[w + 7..]);
-                self.indent -= 2;
+                let where_clause = &after_set[w + 7..];
+                if let Some(ret_idx) = where_clause.find(" RETURNING ") {
+                    self.push_line("WHERE");
+                    self.indent += 2;
+                    self.push_line(&where_clause[..ret_idx]);
+                    self.indent -= 2;
+                    self.push_line(&where_clause[ret_idx + 1..]);
+                } else {
+                    self.push_line("WHERE");
+                    self.indent += 2;
+                    self.push_line(where_clause);
+                    self.indent -= 2;
+                }
             }
         } else {
             self.push_line(&s);
@@ -341,7 +360,7 @@ impl SqlFormatter {
             }
 
             Expr::Value(sqlparser::ast::ValueWithSpan { value: Value::SingleQuotedString(s), .. }) | Expr::Value(sqlparser::ast::ValueWithSpan { value: Value::EscapedStringLiteral(s), .. }) => {
-                if s.starts_with('{') && s.ends_with('}') {
+                if s.starts_with('{') && s.ends_with('}') && s.len() > 2 {
                     if let Ok(json) = serde_json::from_str::<serde_json::Value>(s) {
                         if let Ok(pretty) = serde_json::to_string_pretty(&json) {
                             let lines: Vec<&str> = pretty.split('\n').collect();

src/tests/mod.rs

@@ -104,7 +104,7 @@ fn test_library_api() {
             },
             "types": {
                 "source_schema": {
-                    "default_fields": [],
+                    "field_defaults": {},
                     "field_types": null,
                     "fields": [],
                     "grouped_fields": null,
@@ -169,7 +169,7 @@ fn test_library_api() {
                     "variations": ["source_schema"]
                 },
                 "target_schema": {
-                    "default_fields": [],
+                    "field_defaults": {},
                     "field_types": null,
                     "fields": [],
                     "grouped_fields": null,

version

@@ -1 +1 @@
-1.0.187
+1.0.198