version: 1.0.190

fixtures/properties.json

@@ -888,7 +888,7 @@
                 },
                 "created_at": {
                   "type": "string",
-                  "immutable": true
+                  "immutable": "always"
                 }
               }
             },
@@ -899,7 +899,7 @@
                 },
                 "created_at": {
                   "type": "string",
-                  "immutable": true
+                  "immutable": "always"
                 }
               }
             }
@@ -945,5 +945,70 @@
         }
       }
     ]
+  },
+  {
+    "description": "immutable external vs always property validation",
+    "database": {
+      "types": [
+        {
+          "name": "invoice",
+          "schemas": {
+            "save_invoice.request": {
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string",
+                  "immutable": "external"
+                },
+                "created_at": {
+                  "type": "string",
+                  "immutable": "always"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "tests": [
+      {
+        "description": "immutable external property in request context allowed when internal (punc.external = false)",
+        "data": {
+          "id": "123",
+          "status": "paid"
+        },
+        "schema_id": "save_invoice.request",
+        "action": "validate",
+        "expect": {
+          "success": true
+        }
+      },
+      {
+        "description": "immutable always property in request context rejected even when internal (punc.external = false)",
+        "data": {
+          "id": "123",
+          "created_at": "2026-07-21T00:00:00Z"
+        },
+        "schema_id": "save_invoice.request",
+        "action": "validate",
+        "expect": {
+          "success": false,
+          "errors": [
+            {
+              "code": "IMMUTABLE_PROPERTY_VIOLATION",
+              "values": {
+                "property_name": "created_at"
+              },
+              "details": {
+                "path": "created_at",
+                "schema": "save_invoice.request"
+              }
+            }
+          ]
+        }
+      }
+    ]
   }
 ]

src/database/executors/mock.rs

@@ -13,6 +13,7 @@ pub struct MockState {
   pub query_responses: Vec<Result<Value, String>>,
   pub execute_responses: Vec<Result<(), String>>,
   pub mocks: Vec<Value>,
+  pub punc_external: bool,
 }
 
 #[cfg(test)]
@@ -23,10 +24,12 @@ impl MockState {
       query_responses: Default::default(),
       execute_responses: Default::default(),
       mocks: Default::default(),
+      punc_external: false,
     }
   }
 }
 
+
 #[cfg(test)]
 thread_local! {
   pub static MOCK_STATE: RefCell<MockState> = RefCell::new(MockState::new());
@@ -85,6 +88,10 @@ impl DatabaseExecutor for MockExecutor {
     Ok("2026-03-10T00:00:00Z".to_string())
   }
 
+  fn punc_external(&self) -> Result<bool, String> {
+    Ok(MOCK_STATE.with(|state| state.borrow().punc_external))
+  }
+
   #[cfg(test)]
   fn get_queries(&self) -> Vec<String> {
     MOCK_STATE.with(|state| state.borrow().captured_queries.clone())
@@ -105,10 +112,21 @@ impl DatabaseExecutor for MockExecutor {
       s.query_responses.clear();
       s.execute_responses.clear();
       s.mocks.clear();
+      s.punc_external = false;
     });
   }
 }
 
+#[cfg(test)]
+impl MockExecutor {
+  pub fn set_punc_external(&self, external: bool) {
+    MOCK_STATE.with(|state| {
+      state.borrow_mut().punc_external = external;
+    });
+  }
+}
+
+
 #[cfg(test)]
 fn parse_and_match_mocks(sql: &str, mocks: &[Value]) -> Option<Vec<Value>> {
   let sql_upper = sql.to_uppercase();

src/database/executors/mod.rs

@@ -20,6 +20,9 @@ pub trait DatabaseExecutor: Send + Sync {
   /// Returns the current transaction timestamp
   fn timestamp(&self) -> Result<String, String>;
 
+  /// Returns true if the current execution context is marked as an external client API cue (punc.external = true)
+  fn punc_external(&self) -> Result<bool, String>;
+
   #[cfg(test)]
   fn get_queries(&self) -> Vec<String>;
 

src/database/executors/pgrx.rs

@@ -150,4 +150,26 @@ impl DatabaseExecutor for SpiExecutor {
       })
     })
   }
+
+  fn punc_external(&self) -> Result<bool, String> {
+    self.transact(|| {
+      Spi::connect(|client| {
+        let mut tup_table = client
+          .select(
+            "SELECT COALESCE(current_setting('punc.external', true), 'false')::boolean",
+            None,
+            &[],
+          )
+          .map_err(|e| format!("SPI Select Error: {}", e))?;
+
+        let row = tup_table
+          .next()
+          .ok_or("No setting returned from context".to_string())?;
+        let is_external: Option<bool> = row.get(1).map_err(|e| e.to_string())?;
+
+        Ok(is_external.unwrap_or(false))
+      })
+    })
+  }
 }
+

src/database/object.rs

@@ -151,19 +151,7 @@ pub struct SchemaObject {
   pub extensible: Option<bool>,
   #[serde(default)]
   #[serde(skip_serializing_if = "Option::is_none")]
-  pub immutable: Option<bool>,
-  // readOnly = the CLIENT may not write it; the SERVER still may. Deliberately NOT
-  // enforced here (see validator/rules/object.rs, which rejects `immutable` on any
-  // request) — enforcing it would break legitimate server writers such as the
-  // Mercury feed matcher stamping `reconciliation_status`, or the rollup triggers
-  // that own `total_amount`/`amount_paid`. It is carried purely so it survives
-  // compilation and reaches the punc code generator, which turns it into a
-  // client-side immutable Reactor. Without this field the key was silently dropped
-  // at this boundary and ten authored declarations did nothing for months.
-  #[serde(default)]
-  #[serde(rename = "readOnly")]
-  #[serde(skip_serializing_if = "Option::is_none")]
-  pub read_only: Option<bool>,
+  pub immutable: Option<ImmutableMode>,
 
   // Contains ALL structural fields perfectly flattened from the ENTIRE Database inheritance tree (e.g. `entity` fields like `id`) as well as local fields hidden inside conditional `cases` blocks.
   // This JSON exported array gives clients absolute deterministic visibility to O(1) validation and masking bounds without duplicating structural memory.
@@ -275,6 +263,13 @@ pub fn is_primitive_type(t: &str) -> bool {
   )
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ImmutableMode {
+  Always,
+  External,
+}
+
 impl SchemaObject {
   pub fn get_discriminator_value(&self, dim: &str, schema_id: &str) -> Option<String> {
     let is_split = self
@@ -322,7 +317,11 @@ impl SchemaObject {
     false
   }
 
-  pub fn is_immutable(&self) -> bool {
-    self.immutable == Some(true)
+  pub fn is_immutable(&self, is_external: bool) -> bool {
+    match self.immutable {
+      Some(ImmutableMode::Always) => true,
+      Some(ImmutableMode::External) => is_external,
+      None => false,
+    }
   }
 }

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()
                 },
               });
@@ -289,10 +306,6 @@ impl Merger {
       }
 
       if let Some(prop_schema) = compiled_props.get(&k) {
-        if prop_schema.is_immutable() {
-          continue;
-        }
-
         let mut is_edge = false;
         if let Some(edges) = schema.obj.compiled_edges.get() {
           if edges.contains_key(&k) {
@@ -369,7 +382,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([
@@ -378,7 +394,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()
                   },
                 });
@@ -825,9 +844,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()
             },
           })
@@ -900,9 +925,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()
           },
         });

src/tests/fixtures.rs

@@ -2531,6 +2531,18 @@ fn test_properties_13_1() {
     crate::tests::runner::run_test_case(&path, 13, 1).unwrap();
 }
 
+#[test]
+fn test_properties_14_0() {
+    let path = format!("{}/fixtures/properties.json", env!("CARGO_MANIFEST_DIR"));
+    crate::tests::runner::run_test_case(&path, 14, 0).unwrap();
+}
+
+#[test]
+fn test_properties_14_1() {
+    let path = format!("{}/fixtures/properties.json", env!("CARGO_MANIFEST_DIR"));
+    crate::tests::runner::run_test_case(&path, 14, 1).unwrap();
+}
+
 #[test]
 fn test_max_contains_0_0() {
     let path = format!("{}/fixtures/maxContains.json", env!("CARGO_MANIFEST_DIR"));

src/validator/rules/object.rs

@@ -180,9 +180,10 @@ impl<'a> ValidationContext<'a> {
       }
 
       if !self.response {
+        let is_external = self.db.executor.punc_external().unwrap_or(false);
         if let Some(compiled_props) = self.schema.compiled_properties.get() {
           for (key, sub_schema) in compiled_props {
-            if sub_schema.is_immutable() && obj.contains_key(key) {
+            if sub_schema.is_immutable(is_external) && obj.contains_key(key) {
               result.errors.push(ValidationError {
                 code: "IMMUTABLE_PROPERTY_VIOLATION".to_string(),
                 values: Some(IndexMap::from([
@@ -194,7 +195,7 @@ impl<'a> ValidationContext<'a> {
           }
         } else if let Some(props) = &self.schema.properties {
           for (key, sub_schema) in props {
-            if sub_schema.is_immutable() && obj.contains_key(key) {
+            if sub_schema.is_immutable(is_external) && obj.contains_key(key) {
               result.errors.push(ValidationError {
                 code: "IMMUTABLE_PROPERTY_VIOLATION".to_string(),
                 values: Some(IndexMap::from([
@@ -207,6 +208,8 @@ impl<'a> ValidationContext<'a> {
         }
       }
 
+
+
       if let Some(props) = &self.schema.properties {
         for (key, sub_schema) in props {
           if self.overrides.contains(key) {

version

@@ -1 +1 @@
-1.0.186
+1.0.190