@lix-js/sdk 0.6.0-preview.4 → 0.6.0

package/dist-engine-src/src/catalog/snapshot.rs

@@ -1,1114 +0,0 @@
-use std::{collections::BTreeMap, sync::Arc};
-
-use jsonschema::JSONSchema;
-use serde_json::{Map as JsonMap, Value as JsonValue};
-
-use crate::common::{format_json_pointer, parse_json_pointer};
-use crate::domain::{Domain, DomainSchemaIdentity};
-use crate::entity_identity::canonical_json_text;
-use crate::functions::FunctionProviderHandle;
-use crate::schema::{compile_lix_schema, validate_schema_amendment, SchemaKey};
-use crate::LixError;
-
-#[derive(Default)]
-pub(crate) struct CatalogSnapshot {
-    entries: Vec<CatalogEntry>,
-    plans: Vec<SchemaPlan>,
-    by_key: BTreeMap<SchemaCatalogKey, SchemaPlanId>,
-    by_identity: BTreeMap<DomainSchemaIdentity, SchemaPlanId>,
-    delete_references_by_target: BTreeMap<SchemaCatalogKey, Vec<DeleteReferencePlan>>,
-    state_delete_references: Vec<StateDeleteReferencePlan>,
-    fingerprint: CatalogFingerprint,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct CatalogEntry {
-    identity: DomainSchemaIdentity,
-    key: SchemaCatalogKey,
-    schema: JsonValue,
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub(crate) struct CatalogFingerprint(String);
-
-impl std::fmt::Debug for CatalogSnapshot {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("CatalogSnapshot")
-            .field("plan_count", &self.plans.len())
-            .field("keys", &self.by_key.keys().collect::<Vec<_>>())
-            .finish()
-    }
-}
-
-impl CatalogSnapshot {
-    #[cfg(test)]
-    pub(crate) fn from_visible_schemas(visible_schemas: &[JsonValue]) -> Result<Self, LixError> {
-        let mut catalog = Self::default();
-        for schema in visible_schemas {
-            let key = crate::schema::schema_key_from_definition(schema)?;
-            let catalog_key = SchemaCatalogKey::from_schema_key(key);
-            let identity = DomainSchemaIdentity::new(
-                Domain::schema_catalog(crate::GLOBAL_VERSION_ID, true),
-                catalog_key.schema_key.clone(),
-            );
-            catalog.remember_schema_identity(identity, catalog_key, schema.clone())?;
-        }
-        catalog.rebuild_plans()?;
-        Ok(catalog)
-    }
-
-    pub(crate) fn from_schema_facts(facts: &[SchemaCatalogFact]) -> Result<Self, LixError> {
-        let entries = facts
-            .iter()
-            .map(|fact| CatalogEntry {
-                identity: fact.identity.clone(),
-                key: fact.catalog_key.clone(),
-                schema: fact.schema.clone(),
-            })
-            .collect::<Vec<_>>();
-        Self::from_entries(entries)
-    }
-
-    #[cfg(test)]
-    pub(crate) fn fingerprint(&self) -> &CatalogFingerprint {
-        &self.fingerprint
-    }
-
-    pub(crate) fn schema(&self, schema_key: &str) -> Option<&JsonValue> {
-        self.plan_for_key(schema_key)
-            .map(|(_, plan)| plan.schema.as_ref())
-    }
-
-    pub(crate) fn insert_schema_for_domain(
-        &mut self,
-        domain: Domain,
-        key: SchemaKey,
-        schema: JsonValue,
-    ) -> Result<SchemaPlanId, LixError> {
-        let key = SchemaCatalogKey::from_schema_key(key);
-        let identity = DomainSchemaIdentity::new(domain, key.schema_key.clone());
-        let mut entries = self.entries.clone();
-        let mut candidate = Self::from_entries(entries.clone())?;
-        let plan_id = candidate.remember_schema_identity(identity.clone(), key, schema)?;
-        entries = candidate.entries.clone();
-        let candidate = Self::from_entries(entries)?;
-        *self = candidate;
-        Ok(self.by_identity.get(&identity).copied().unwrap_or(plan_id))
-    }
-
-    fn from_entries(entries: Vec<CatalogEntry>) -> Result<Self, LixError> {
-        let mut catalog = Self::default();
-        for entry in entries {
-            catalog.remember_schema_identity(entry.identity, entry.key, entry.schema)?;
-        }
-        catalog.rebuild_plans()?;
-        Ok(catalog)
-    }
-
-    fn remember_schema_identity(
-        &mut self,
-        identity: DomainSchemaIdentity,
-        key: SchemaCatalogKey,
-        schema: JsonValue,
-    ) -> Result<SchemaPlanId, LixError> {
-        if let Some(existing) = self.by_identity.get(&identity).copied() {
-            let existing_entry = &self.entries[existing.index()];
-            if existing_entry.key == key && existing_entry.schema == schema {
-                return Ok(existing);
-            }
-            if existing_entry.key == key {
-                validate_schema_amendment(&existing_entry.schema, &schema)?;
-                self.entries[existing.index()].schema = schema;
-                return Ok(existing);
-            }
-            return Err(LixError::new(
-                LixError::CODE_SCHEMA_DEFINITION,
-                format!("schema '{}' is already registered with a different definition in the same schema domain", key.schema_key),
-            ));
-        }
-        if let Some(existing) = self.by_key.get(&key).copied() {
-            let existing_entry = &self.entries[existing.index()];
-            if existing_entry.identity == identity {
-                return Ok(existing);
-            }
-            return Err(LixError::new(
-                LixError::CODE_SCHEMA_DEFINITION,
-                format!("schema '{}' is visible from more than one schema domain", existing_entry.key.schema_key),
-            )
-            .with_hint("Schema references store schema_key, but not the schema domain. Remove the duplicate tracked/untracked schema registration or use a distinct schema key."));
-        }
-
-        let plan_id = SchemaPlanId(self.entries.len() as u32);
-        self.by_key.insert(key.clone(), plan_id);
-        self.by_identity.insert(identity.clone(), plan_id);
-        self.entries.push(CatalogEntry {
-            identity,
-            key,
-            schema,
-        });
-        Ok(plan_id)
-    }
-
-    fn rebuild_plans(&mut self) -> Result<(), LixError> {
-        let schema_index = self
-            .entries
-            .iter()
-            .map(|entry| (entry.key.clone(), &entry.schema))
-            .collect::<BTreeMap<_, _>>();
-        let plans = self
-            .entries
-            .iter()
-            .map(|entry| {
-                SchemaPlan::compile(
-                    entry.key.clone(),
-                    entry.schema.clone(),
-                    &self.by_key,
-                    &schema_index,
-                )
-            })
-            .collect::<Result<Vec<_>, _>>()?;
-        self.plans = plans;
-        self.rebuild_delete_plans();
-        self.fingerprint = self.compute_fingerprint()?;
-        Ok(())
-    }
-
-    fn rebuild_delete_plans(&mut self) {
-        let mut delete_references_by_target =
-            BTreeMap::<SchemaCatalogKey, Vec<DeleteReferencePlan>>::new();
-        let mut state_delete_references = Vec::<StateDeleteReferencePlan>::new();
-        for source_plan in &self.plans {
-            for foreign_key in &source_plan.foreign_keys {
-                delete_references_by_target
-                    .entry(foreign_key.referenced_schema.clone())
-                    .or_default()
-                    .push(DeleteReferencePlan {
-                        source_key: source_plan.key.clone(),
-                        foreign_key: foreign_key.clone(),
-                    });
-            }
-            for foreign_key in &source_plan.state_foreign_keys {
-                state_delete_references.push(StateDeleteReferencePlan {
-                    source_key: source_plan.key.clone(),
-                    foreign_key: foreign_key.clone(),
-                });
-            }
-        }
-        self.delete_references_by_target = delete_references_by_target;
-        self.state_delete_references = state_delete_references;
-    }
-
-    fn compute_fingerprint(&self) -> Result<CatalogFingerprint, LixError> {
-        let mut hasher = blake3::Hasher::new();
-        let mut entries = self.entries.iter().collect::<Vec<_>>();
-        entries.sort_by(|left, right| left.identity.cmp(&right.identity));
-        for entry in entries {
-            hash_fingerprint_part(&mut hasher, &entry.identity.fingerprint_component());
-            hash_fingerprint_part(&mut hasher, &entry.key.schema_key);
-            let canonical_schema = canonical_json_text(&entry.schema).map_err(|error| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("failed to canonicalize schema for catalog fingerprint: {error}"),
-                )
-            })?;
-            hash_fingerprint_part(&mut hasher, &canonical_schema);
-        }
-        Ok(CatalogFingerprint(hasher.finalize().to_hex().to_string()))
-    }
-
-    #[cfg(test)]
-    pub(crate) fn contains(&self, schema_key: &str) -> bool {
-        self.plan_for_key(schema_key).is_some()
-    }
-
-    #[cfg(test)]
-    pub(crate) fn len(&self) -> usize {
-        self.plans.len()
-    }
-
-    pub(crate) fn plans(&self) -> impl Iterator<Item = &SchemaPlan> {
-        self.plans.iter()
-    }
-
-    pub(crate) fn plan(&self, plan_id: SchemaPlanId) -> Option<&SchemaPlan> {
-        self.plans.get(plan_id.index())
-    }
-
-    pub(crate) fn plan_for_key(&self, schema_key: &str) -> Option<(SchemaPlanId, &SchemaPlan)> {
-        let key = SchemaCatalogKey {
-            schema_key: schema_key.to_string(),
-        };
-        let plan_id = *self.by_key.get(&key)?;
-        let plan = self.plan(plan_id)?;
-        Some((plan_id, plan))
-    }
-
-    pub(crate) fn delete_plan_for_key(&self, schema_key: &str) -> DeleteValidationPlan<'_> {
-        let key = SchemaCatalogKey {
-            schema_key: schema_key.to_string(),
-        };
-        DeleteValidationPlan {
-            foreign_key_references: self
-                .delete_references_by_target
-                .get(&key)
-                .map(Vec::as_slice)
-                .unwrap_or(&[]),
-            state_foreign_key_references: self.state_delete_references.as_slice(),
-        }
-    }
-}
-
-fn hash_fingerprint_part(hasher: &mut blake3::Hasher, value: &str) {
-    hasher.update(&(value.len() as u64).to_le_bytes());
-    hasher.update(value.as_bytes());
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub(crate) struct SchemaPlanId(u32);
-
-impl SchemaPlanId {
-    fn index(self) -> usize {
-        self.0 as usize
-    }
-
-    #[cfg(test)]
-    pub(crate) fn for_test(index: u32) -> Self {
-        Self(index)
-    }
-}
-
-pub(crate) type PointerGroup = Vec<Vec<String>>;
-
-pub(crate) struct SchemaPlan {
-    pub(crate) key: SchemaCatalogKey,
-    pub(crate) schema: Arc<JsonValue>,
-    pub(crate) compiled_schema: JSONSchema,
-    pub(crate) defaults: DefaultPlan,
-    pub(crate) primary_key: Option<PointerGroup>,
-    pub(crate) uniques: Vec<PointerGroup>,
-    pub(crate) foreign_keys: Vec<ForeignKeyPlan>,
-    pub(crate) state_foreign_keys: Vec<StateForeignKeyPlan>,
-}
-
-impl SchemaPlan {
-    fn compile(
-        key: SchemaCatalogKey,
-        schema: JsonValue,
-        key_index: &BTreeMap<SchemaCatalogKey, SchemaPlanId>,
-        schema_index: &BTreeMap<SchemaCatalogKey, &JsonValue>,
-    ) -> Result<Self, LixError> {
-        let compiled_schema = compile_lix_schema(&schema)?;
-        let defaults = DefaultPlan::from_schema(&schema);
-        let primary_key = primary_key_paths(&schema)?;
-        let uniques = pointer_groups(&schema, "x-lix-unique")?;
-        let foreign_keys = bind_foreign_key_plans(
-            &key,
-            &schema,
-            foreign_key_plans(&schema)?,
-            key_index,
-            schema_index,
-        )?;
-        let state_foreign_keys = state_foreign_key_plans(&schema)?;
-        Ok(Self {
-            key,
-            schema: Arc::new(schema),
-            compiled_schema,
-            defaults,
-            primary_key,
-            uniques,
-            foreign_keys,
-            state_foreign_keys,
-        })
-    }
-}
-
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub(crate) struct DefaultPlan {
-    properties: Vec<DefaultPropertyPlan>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct DefaultPropertyPlan {
-    field_name: String,
-    default: DefaultValuePlan,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-enum DefaultValuePlan {
-    Json(JsonValue),
-    Cel(String),
-}
-
-impl DefaultPlan {
-    fn from_schema(schema: &JsonValue) -> Self {
-        let Some(properties) = schema.get("properties").and_then(JsonValue::as_object) else {
-            return Self::default();
-        };
-        let mut ordered_properties = properties.iter().collect::<Vec<_>>();
-        ordered_properties.sort_by(|(left_name, _), (right_name, _)| left_name.cmp(right_name));
-
-        let properties = ordered_properties
-            .into_iter()
-            .filter_map(|(field_name, field_schema)| {
-                if let Some(expression) = field_schema
-                    .get("x-lix-default")
-                    .and_then(JsonValue::as_str)
-                {
-                    return Some(DefaultPropertyPlan {
-                        field_name: field_name.clone(),
-                        default: DefaultValuePlan::Cel(expression.to_string()),
-                    });
-                }
-                field_schema
-                    .get("default")
-                    .map(|value| DefaultPropertyPlan {
-                        field_name: field_name.clone(),
-                        default: DefaultValuePlan::Json(value.clone()),
-                    })
-            })
-            .collect();
-        Self { properties }
-    }
-
-    pub(crate) fn apply(
-        &self,
-        snapshot: &mut JsonMap<String, JsonValue>,
-        functions: FunctionProviderHandle,
-        schema_key: &str,
-    ) -> Result<bool, LixError> {
-        let mut changed = false;
-        let mut cel_context = None::<JsonMap<String, JsonValue>>;
-        for property in &self.properties {
-            if snapshot.contains_key(&property.field_name) {
-                continue;
-            }
-            let value = match &property.default {
-                DefaultValuePlan::Json(value) => value.clone(),
-                DefaultValuePlan::Cel(expression) => {
-                    let context = cel_context.get_or_insert_with(|| snapshot.clone());
-                    crate::cel::shared_runtime()
-                        .evaluate_with_functions(expression, context, functions.clone())
-                        .map_err(|err| LixError {
-                            code: "LIX_ERROR_UNKNOWN".to_string(),
-                            message: format!(
-                                "failed to evaluate x-lix-default for '{}.{}': {}",
-                                schema_key, property.field_name, err.message
-                            ),
-                            hint: None,
-                            details: None,
-                        })?
-                }
-            };
-            snapshot.insert(property.field_name.clone(), value);
-            changed = true;
-        }
-        Ok(changed)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct ForeignKeyPlan {
-    pub(crate) local_properties: PointerGroup,
-    pub(crate) referenced_schema: SchemaCatalogKey,
-    pub(crate) referenced_plan_id: SchemaPlanId,
-    pub(crate) referenced_properties: PointerGroup,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct DeleteReferencePlan {
-    pub(crate) source_key: SchemaCatalogKey,
-    pub(crate) foreign_key: ForeignKeyPlan,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
-pub(crate) struct StateDeleteReferencePlan {
-    pub(crate) source_key: SchemaCatalogKey,
-    pub(crate) foreign_key: StateForeignKeyPlan,
-}
-
-#[derive(Debug, Clone, Copy)]
-pub(crate) struct DeleteValidationPlan<'a> {
-    pub(crate) foreign_key_references: &'a [DeleteReferencePlan],
-    pub(crate) state_foreign_key_references: &'a [StateDeleteReferencePlan],
-}
-
-impl DeleteValidationPlan<'_> {
-    pub(crate) fn has_committed_checks(self) -> bool {
-        !self.foreign_key_references.is_empty() || !self.state_foreign_key_references.is_empty()
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct UnboundForeignKeyPlan {
-    local_properties: PointerGroup,
-    referenced_schema: SchemaCatalogKey,
-    referenced_properties: PointerGroup,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
-pub(crate) struct StateForeignKeyPlan {
-    /// Slot [0] in `x-lix-state-foreign-keys`: local pointer to the target entity_id.
-    pub(crate) entity_id_property: Vec<String>,
-    /// Slot [1] in `x-lix-state-foreign-keys`: local pointer to the target schema_key.
-    pub(crate) schema_key_property: Vec<String>,
-    /// Slot [2] in `x-lix-state-foreign-keys`: local pointer to the target file_id.
-    pub(crate) file_id_property: Vec<String>,
-}
-
-impl StateForeignKeyPlan {
-    pub(crate) fn local_properties(&self) -> PointerGroup {
-        vec![
-            self.entity_id_property.clone(),
-            self.schema_key_property.clone(),
-            self.file_id_property.clone(),
-        ]
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
-pub(crate) struct SchemaCatalogKey {
-    pub(crate) schema_key: String,
-}
-
-impl SchemaCatalogKey {
-    pub(crate) fn from_schema_key(key: SchemaKey) -> Self {
-        Self {
-            schema_key: key.schema_key,
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct SchemaCatalogFact {
-    identity: DomainSchemaIdentity,
-    catalog_key: SchemaCatalogKey,
-    schema: JsonValue,
-}
-
-impl SchemaCatalogFact {
-    pub(crate) fn new(domain: Domain, key: SchemaKey, schema: JsonValue) -> Self {
-        let catalog_key = SchemaCatalogKey::from_schema_key(key);
-        let identity = DomainSchemaIdentity::new(domain, catalog_key.schema_key.clone());
-        Self {
-            identity,
-            catalog_key,
-            schema,
-        }
-    }
-
-    pub(crate) fn schema(&self) -> &JsonValue {
-        &self.schema
-    }
-
-    pub(crate) fn catalog_key(&self) -> &SchemaCatalogKey {
-        &self.catalog_key
-    }
-}
-
-fn primary_key_paths(schema: &JsonValue) -> Result<Option<Vec<Vec<String>>>, LixError> {
-    let Some(primary_key) = schema.get("x-lix-primary-key") else {
-        return Ok(None);
-    };
-    let primary_key = primary_key.as_array().ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            "schema x-lix-primary-key must be an array of JSON Pointers",
-        )
-    })?;
-    primary_key
-        .iter()
-        .enumerate()
-        .map(|(index, pointer)| {
-            let pointer = pointer.as_str().ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("schema x-lix-primary-key entry at index {index} must be a string"),
-                )
-            })?;
-            parse_json_pointer(pointer)
-        })
-        .collect::<Result<Vec<_>, _>>()
-        .map(Some)
-}
-
-fn pointer_groups(schema: &JsonValue, field: &str) -> Result<Vec<PointerGroup>, LixError> {
-    let Some(value) = schema.get(field) else {
-        return Ok(Vec::new());
-    };
-    let groups = value
-        .as_array()
-        .map(|groups| groups.iter().collect::<Vec<_>>())
-        .unwrap_or_default();
-    groups
-        .into_iter()
-        .map(|group| {
-            let group = group.as_array().ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("schema {field} must contain arrays of JSON Pointers"),
-                )
-            })?;
-            group
-                .iter()
-                .enumerate()
-                .map(|(index, pointer)| {
-                    let pointer = pointer.as_str().ok_or_else(|| {
-                        LixError::new(
-                            LixError::CODE_SCHEMA_DEFINITION,
-                            format!("schema {field} entry at index {index} must be a string"),
-                        )
-                    })?;
-                    parse_json_pointer(pointer)
-                })
-                .collect::<Result<Vec<_>, _>>()
-        })
-        .collect()
-}
-
-fn foreign_key_plans(schema: &JsonValue) -> Result<Vec<UnboundForeignKeyPlan>, LixError> {
-    let Some(value) = schema.get("x-lix-foreign-keys") else {
-        return Ok(Vec::new());
-    };
-    let Some(foreign_keys) = value.as_array() else {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            "schema x-lix-foreign-keys must be an array",
-        ));
-    };
-
-    foreign_keys
-        .iter()
-        .enumerate()
-        .map(|(index, foreign_key)| {
-            let object = foreign_key.as_object().ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("x-lix-foreign-keys[{index}] must be an object"),
-                )
-            })?;
-            let references = object
-                .get("references")
-                .and_then(JsonValue::as_object)
-                .ok_or_else(|| {
-                    LixError::new(
-                        LixError::CODE_SCHEMA_DEFINITION,
-                        format!("x-lix-foreign-keys[{index}].references must be an object"),
-                    )
-                })?;
-            let referenced_schema_key = references
-                .get("schemaKey")
-                .and_then(JsonValue::as_str)
-                .ok_or_else(|| {
-                    LixError::new(
-                        LixError::CODE_SCHEMA_DEFINITION,
-                        format!(
-                            "x-lix-foreign-keys[{index}].references.schemaKey must be a string"
-                        ),
-                    )
-                })?
-                .to_string();
-            let local_properties = pointer_array(
-                object.get("properties"),
-                &format!("x-lix-foreign-keys[{index}].properties"),
-            )?;
-            let referenced_properties = pointer_array(
-                references.get("properties"),
-                &format!("x-lix-foreign-keys[{index}].references.properties"),
-            )?;
-            if local_properties.len() != referenced_properties.len() {
-                return Err(LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!(
-                        "x-lix-foreign-keys[{index}] properties and references.properties must have the same length"
-                    ),
-                ));
-            }
-            Ok(UnboundForeignKeyPlan {
-                local_properties,
-                referenced_schema: SchemaCatalogKey {
-                    schema_key: referenced_schema_key,
-                },
-                referenced_properties,
-            })
-        })
-        .collect()
-}
-
-fn bind_foreign_key_plans(
-    source_key: &SchemaCatalogKey,
-    source_schema: &JsonValue,
-    unbound_foreign_keys: Vec<UnboundForeignKeyPlan>,
-    key_index: &BTreeMap<SchemaCatalogKey, SchemaPlanId>,
-    schema_index: &BTreeMap<SchemaCatalogKey, &JsonValue>,
-) -> Result<Vec<ForeignKeyPlan>, LixError> {
-    unbound_foreign_keys
-        .into_iter()
-        .map(|foreign_key| {
-            if foreign_key.referenced_schema.schema_key == "lix_state" {
-                return Err(LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!(
-                        "foreign key on schema '{}' must not reference schemaKey 'lix_state'; use x-lix-state-foreign-keys with pointers ordered as [entity_id, schema_key, file_id]",
-                        source_key.schema_key
-                    ),
-                ));
-            }
-
-            let referenced_plan_id =
-                *key_index.get(&foreign_key.referenced_schema).ok_or_else(|| {
-                    LixError::new(
-                        LixError::CODE_SCHEMA_DEFINITION,
-                        format!(
-                            "foreign key on schema '{}' references missing schema '{}'",
-                            source_key.schema_key,
-                            foreign_key.referenced_schema.schema_key,
-                        ),
-                    )
-                })?;
-            let target_schema =
-                schema_index
-                    .get(&foreign_key.referenced_schema)
-                    .copied()
-                    .ok_or_else(|| {
-                        LixError::new(
-                        LixError::CODE_SCHEMA_DEFINITION,
-                        format!(
-                                "foreign key on schema '{}' references missing schema '{}'",
-                                source_key.schema_key,
-                                foreign_key.referenced_schema.schema_key,
-                            ),
-                    )
-                })?;
-
-            for (local_pointer, referenced_pointer) in foreign_key
-                .local_properties
-                .iter()
-                .zip(foreign_key.referenced_properties.iter())
-            {
-                let local_field =
-                    schema_field_at_pointer(source_schema, local_pointer).map_err(|detail| {
-                        LixError::new(
-                            LixError::CODE_SCHEMA_DEFINITION,
-                            format!(
-                                "foreign key on schema '{}' references missing local property '{}': {detail}",
-                                source_key.schema_key,
-                                format_json_pointer(local_pointer)
-                            ),
-                        )
-                    })?;
-                let referenced_field =
-                    schema_field_at_pointer(target_schema, referenced_pointer).map_err(
-                        |detail| {
-                            LixError::new(
-                                LixError::CODE_SCHEMA_DEFINITION,
-                                format!(
-                                    "foreign key on schema '{}' references missing target property '{}.{}': {detail}",
-                                    source_key.schema_key,
-                                    foreign_key.referenced_schema.schema_key,
-                                    format_json_pointer(referenced_pointer)
-                                ),
-                            )
-                        },
-                    )?;
-                validate_foreign_key_field_types(
-                    source_key,
-                    &foreign_key.referenced_schema,
-                    local_pointer,
-                    local_field,
-                    referenced_pointer,
-                    referenced_field,
-                )?;
-            }
-
-            if !schema_properties_are_keyed(target_schema, &foreign_key.referenced_properties)? {
-                return Err(LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!(
-                        "foreign key on schema '{}' references '{}.{}', but referenced properties must match the target primary key or a unique constraint",
-                        source_key.schema_key,
-                        foreign_key.referenced_schema.schema_key,
-                        format_pointer_group(&foreign_key.referenced_properties)
-                    ),
-                ));
-            }
-
-            Ok(ForeignKeyPlan {
-                local_properties: foreign_key.local_properties,
-                referenced_schema: foreign_key.referenced_schema,
-                referenced_plan_id,
-                referenced_properties: foreign_key.referenced_properties,
-            })
-        })
-        .collect()
-}
-
-fn schema_field_at_pointer<'a>(
-    schema: &'a JsonValue,
-    pointer: &[String],
-) -> Result<&'a JsonValue, String> {
-    if pointer.is_empty() {
-        return Err("empty pointer does not name a field".to_string());
-    }
-    let mut current = schema;
-    for segment in pointer {
-        let properties = current
-            .get("properties")
-            .and_then(JsonValue::as_object)
-            .ok_or_else(|| {
-                format!(
-                    "schema segment before '{}' has no object properties",
-                    segment
-                )
-            })?;
-        current = properties
-            .get(segment)
-            .ok_or_else(|| format!("property '{}' does not exist", segment))?;
-    }
-    Ok(current)
-}
-
-fn validate_foreign_key_field_types(
-    source_key: &SchemaCatalogKey,
-    referenced_key: &SchemaCatalogKey,
-    local_pointer: &[String],
-    local_field: &JsonValue,
-    referenced_pointer: &[String],
-    referenced_field: &JsonValue,
-) -> Result<(), LixError> {
-    let local_type = compatible_json_schema_type(local_field).ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!(
-                "foreign key on schema '{}' local property '{}' must declare an explicit JSON Schema type",
-                source_key.schema_key,
-                format_json_pointer(local_pointer)
-            ),
-        )
-    })?;
-    let referenced_type = compatible_json_schema_type(referenced_field).ok_or_else(|| {
-        LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!(
-                "foreign key on schema '{}' target property '{}.{}' must declare an explicit JSON Schema type",
-                source_key.schema_key,
-                referenced_key.schema_key,
-                format_json_pointer(referenced_pointer)
-            ),
-        )
-    })?;
-    if local_type != referenced_type {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!(
-                "foreign key on schema '{}' has incompatible field types: local '{}' is {}, but target '{}.{}' is {}",
-                source_key.schema_key,
-                format_json_pointer(local_pointer),
-                local_type,
-                referenced_key.schema_key,
-                format_json_pointer(referenced_pointer),
-                referenced_type
-            ),
-        ));
-    }
-    Ok(())
-}
-
-fn compatible_json_schema_type(field_schema: &JsonValue) -> Option<JsonValue> {
-    match field_schema.get("type")? {
-        JsonValue::Array(types) => {
-            let non_null_types = types
-                .iter()
-                .filter(|value| value.as_str() != Some("null"))
-                .cloned()
-                .collect::<Vec<_>>();
-            match non_null_types.as_slice() {
-                [] => None,
-                [single] => Some(single.clone()),
-                _ => Some(JsonValue::Array(non_null_types)),
-            }
-        }
-        value => Some(value.clone()),
-    }
-}
-
-fn schema_properties_are_keyed(
-    target_schema: &JsonValue,
-    referenced_properties: &[Vec<String>],
-) -> Result<bool, LixError> {
-    if let Some(primary_key) = primary_key_paths(target_schema)? {
-        if primary_key == referenced_properties {
-            return Ok(true);
-        }
-    }
-    Ok(pointer_groups(target_schema, "x-lix-unique")?
-        .iter()
-        .any(|unique_group| unique_group == referenced_properties))
-}
-
-fn state_foreign_key_plans(schema: &JsonValue) -> Result<Vec<StateForeignKeyPlan>, LixError> {
-    let Some(value) = schema.get("x-lix-state-foreign-keys") else {
-        return Ok(Vec::new());
-    };
-    let Some(foreign_keys) = value.as_array() else {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            "schema x-lix-state-foreign-keys must be an array",
-        ));
-    };
-
-    foreign_keys
-        .iter()
-        .enumerate()
-        .map(|(index, foreign_key)| {
-            let local_properties = pointer_array(
-                Some(foreign_key),
-                &format!("x-lix-state-foreign-keys[{index}]"),
-            )?;
-            if local_properties.len() != 3 {
-                return Err(LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!(
-                        "x-lix-state-foreign-keys[{index}] must contain exactly three JSON Pointers ordered as [entity_id, schema_key, file_id]"
-                    ),
-                ));
-            }
-            Ok(StateForeignKeyPlan {
-                entity_id_property: local_properties[0].clone(),
-                schema_key_property: local_properties[1].clone(),
-                file_id_property: local_properties[2].clone(),
-            })
-        })
-        .collect()
-}
-
-fn pointer_array(value: Option<&JsonValue>, context: &str) -> Result<PointerGroup, LixError> {
-    let Some(value) = value else {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!("{context} must be an array of JSON Pointers"),
-        ));
-    };
-    let Some(array) = value.as_array() else {
-        return Err(LixError::new(
-            LixError::CODE_SCHEMA_DEFINITION,
-            format!("{context} must be an array of JSON Pointers"),
-        ));
-    };
-    array
-        .iter()
-        .enumerate()
-        .map(|(index, pointer)| {
-            let pointer = pointer.as_str().ok_or_else(|| {
-                LixError::new(
-                    LixError::CODE_SCHEMA_DEFINITION,
-                    format!("{context}[{index}] must be a string"),
-                )
-            })?;
-            parse_json_pointer(pointer)
-        })
-        .collect()
-}
-
-fn format_pointer_group(paths: &[Vec<String>]) -> String {
-    paths
-        .iter()
-        .map(|path| format_json_pointer(path))
-        .collect::<Vec<_>>()
-        .join(",")
-}
-
-#[cfg(test)]
-mod tests {
-    use serde_json::json;
-
-    use super::*;
-
-    #[test]
-    fn catalog_rejects_same_schema_key_from_multiple_domains() {
-        let tracked = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("example_schema"),
-            schema_json("example_schema"),
-        );
-        let untracked = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", true),
-            SchemaKey::new("example_schema"),
-            schema_json("example_schema"),
-        );
-
-        let error = CatalogSnapshot::from_schema_facts(&[tracked, untracked])
-            .expect_err("same schema key in two reachable domains is ambiguous");
-
-        assert_eq!(error.code, LixError::CODE_SCHEMA_DEFINITION);
-        assert!(error.message.contains("more than one schema domain"));
-    }
-
-    #[test]
-    fn insert_schema_for_domain_is_atomic_when_binding_fails() {
-        let mut catalog = CatalogSnapshot::from_schema_facts(&[SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("base_schema"),
-            schema_json("base_schema"),
-        )])
-        .expect("base catalog should bind");
-
-        let error = catalog
-            .insert_schema_for_domain(
-                Domain::schema_catalog("main", false),
-                SchemaKey::new("bad_child_schema"),
-                child_schema_json("bad_child_schema", "missing_parent_schema"),
-            )
-            .expect_err("schema with missing FK target should fail");
-
-        assert_eq!(error.code, LixError::CODE_SCHEMA_DEFINITION);
-        assert!(catalog.contains("base_schema"));
-        assert!(
-            !catalog.contains("bad_child_schema"),
-            "failed catalog insert must not publish a partially bound schema"
-        );
-    }
-
-    #[test]
-    fn catalog_fingerprint_is_independent_of_fact_order() {
-        let parent = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("parent_schema"),
-            schema_json("parent_schema"),
-        );
-        let child = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("child_schema"),
-            child_schema_json("child_schema", "parent_schema"),
-        );
-
-        let parent_first = CatalogSnapshot::from_schema_facts(&[parent.clone(), child.clone()])
-            .expect("parent-first facts should bind");
-        let child_first = CatalogSnapshot::from_schema_facts(&[child, parent])
-            .expect("child-first facts should bind as the same domain snapshot");
-
-        assert_eq!(parent_first.fingerprint(), child_first.fingerprint());
-    }
-
-    #[test]
-    fn delete_plan_has_no_committed_checks_for_unreferenced_schema() {
-        let catalog = CatalogSnapshot::from_schema_facts(&[SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("standalone_schema"),
-            schema_json("standalone_schema"),
-        )])
-        .expect("catalog should bind");
-
-        let delete_plan = catalog.delete_plan_for_key("standalone_schema");
-
-        assert!(!delete_plan.has_committed_checks());
-        assert!(delete_plan.foreign_key_references.is_empty());
-        assert!(delete_plan.state_foreign_key_references.is_empty());
-    }
-
-    #[test]
-    fn delete_plan_indexes_foreign_keys_by_referenced_schema() {
-        let parent = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("parent_schema"),
-            schema_json("parent_schema"),
-        );
-        let child = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("child_schema"),
-            child_schema_json("child_schema", "parent_schema"),
-        );
-        let catalog =
-            CatalogSnapshot::from_schema_facts(&[parent, child]).expect("catalog should bind");
-
-        let parent_delete_plan = catalog.delete_plan_for_key("parent_schema");
-        let child_delete_plan = catalog.delete_plan_for_key("child_schema");
-
-        assert!(parent_delete_plan.has_committed_checks());
-        assert_eq!(parent_delete_plan.foreign_key_references.len(), 1);
-        assert_eq!(
-            parent_delete_plan.foreign_key_references[0]
-                .source_key
-                .schema_key,
-            "child_schema"
-        );
-        assert!(!child_delete_plan.has_committed_checks());
-    }
-
-    #[test]
-    fn delete_plan_conservatively_applies_state_foreign_keys_to_every_schema() {
-        let target = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("target_schema"),
-            schema_json("target_schema"),
-        );
-        let source = SchemaCatalogFact::new(
-            Domain::schema_catalog("main", false),
-            SchemaKey::new("state_fk_schema"),
-            state_fk_schema_json("state_fk_schema"),
-        );
-        let catalog =
-            CatalogSnapshot::from_schema_facts(&[target, source]).expect("catalog should bind");
-
-        let target_delete_plan = catalog.delete_plan_for_key("target_schema");
-
-        assert!(target_delete_plan.has_committed_checks());
-        assert_eq!(target_delete_plan.state_foreign_key_references.len(), 1);
-        assert_eq!(
-            target_delete_plan.state_foreign_key_references[0]
-                .source_key
-                .schema_key,
-            "state_fk_schema"
-        );
-    }
-
-    fn schema_json(schema_key: &str) -> JsonValue {
-        json!({
-            "x-lix-key": schema_key,
-            "x-lix-primary-key": ["/id"],
-            "type": "object",
-            "properties": {
-                "id": { "type": "string" }
-            },
-            "required": ["id"],
-            "additionalProperties": false
-        })
-    }
-
-    fn child_schema_json(schema_key: &str, parent_schema_key: &str) -> JsonValue {
-        json!({
-            "x-lix-key": schema_key,
-            "x-lix-primary-key": ["/id"],
-            "x-lix-foreign-keys": [{
-                "properties": ["/parent_id"],
-                "references": {
-                    "schemaKey": parent_schema_key,
-                    "properties": ["/id"]
-                }
-            }],
-            "type": "object",
-            "properties": {
-                "id": { "type": "string" },
-                "parent_id": { "type": "string" }
-            },
-            "required": ["id", "parent_id"],
-            "additionalProperties": false
-        })
-    }
-
-    fn state_fk_schema_json(schema_key: &str) -> JsonValue {
-        json!({
-            "x-lix-key": schema_key,
-            "x-lix-primary-key": ["/id"],
-            "x-lix-state-foreign-keys": [["/target_id", "/target_schema", "/target_file"]],
-            "type": "object",
-            "properties": {
-                "id": { "type": "string" },
-                "target_id": { "type": "string" },
-                "target_schema": { "type": "string" },
-                "target_file": { "type": ["string", "null"] }
-            },
-            "required": ["id", "target_id", "target_schema", "target_file"],
-            "additionalProperties": false
-        })
-    }
-}