mere-kernel 0.0.3

Portable identity, authority, and mutation kernel for the Mere browser. Renamed from graphshell-core.
Documentation
// Copyright 2026 Mark Alan Boykin
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0

//! Immutable selections owned by Resources, independent of local appearances.
use super::{CoverageNote, Graph, GraphStratum};
use crate::persistence::PersistedEdge;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

pub const FROZEN_SELECTION: &str = "graph.frozen-selection/v1";
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FrozenSelection {
    version: u32,
    spec: serde_json::Value,
    revision: u64,
    members: Vec<Uuid>,
    statements: Vec<PersistedEdge>,
}
impl FrozenSelection {
    pub fn spec(&self) -> &serde_json::Value {
        &self.spec
    }
    pub fn revision(&self) -> u64 {
        self.revision
    }
    pub fn members(&self) -> &[Uuid] {
        &self.members
    }
    pub fn statements(&self) -> &[PersistedEdge] {
        &self.statements
    }
}
pub struct OpenedFrozenSelection<'a> {
    pub selection: &'a FrozenSelection,
    pub coverage: CoverageNote,
}
// Legacy edge DTOs deliberately remain permissive. This v1 carrier checks
// every nested key against what their typed serialization retains instead.
pub(super) fn validate_retained_keys(
    input: &serde_json::Value,
    known: &serde_json::Value,
) -> Result<(), String> {
    match (input, known) {
        (serde_json::Value::Object(input), serde_json::Value::Object(known)) => {
            for (key, value) in input {
                let expected = known
                    .get(key)
                    .ok_or_else(|| format!("unknown frozen payload field {key}"))?;
                validate_retained_keys(value, expected)?;
            }
        },
        (serde_json::Value::Array(input), serde_json::Value::Array(known)) => {
            for (value, expected) in input.iter().zip(known) {
                validate_retained_keys(value, expected)?;
            }
        },
        (serde_json::Value::Object(_), _) | (serde_json::Value::Array(_), _) => {
            return Err("unrepresentable frozen payload shape".into());
        },
        _ => {},
    }
    Ok(())
}

pub(super) fn normalize_statement_defaults(statements: &mut [serde_json::Value]) {
    for statement in statements {
        let object = statement
            .as_object_mut()
            .expect("serialized statement object");
        for field in [
            "recognized_sub_kind",
            "label",
            "graph_scope",
            "provenance_iri",
            "asserted_at_ms",
            "first_asserted_ms",
            "withdrawn",
            "basis",
        ] {
            object.entry(field).or_insert(serde_json::Value::Null);
        }
    }
}

/// Decode and check nested references without requiring member residency.
pub(crate) fn selection_from_record(
    record: &crate::persistence::PersistedResourceRecord,
) -> Result<Option<FrozenSelection>, String> {
    let Some(facet) = record
        .facets
        .iter()
        .find(|facet| facet.facet == FROZEN_SELECTION)
    else {
        return Ok(None);
    };
    let raw: serde_json::Value = serde_json::from_str(&facet.value_json)
        .map_err(|e| format!("invalid frozen selection: {e}"))?;
    let selection: FrozenSelection = serde_json::from_value(raw.clone())
        .map_err(|e| format!("invalid frozen selection: {e}"))?;
    let mut known = serde_json::to_value(&selection).map_err(|e| e.to_string())?;
    // Human-readable statement serialization omits default metadata. Their
    // known fields are still accepted explicitly, including null/default values.
    for edge in known["statements"]
        .as_array_mut()
        .expect("serialized edge array")
    {
        if let Some(statements) = edge
            .get_mut("assertions")
            .and_then(serde_json::Value::as_array_mut)
        {
            normalize_statement_defaults(statements);
        }
        if let Some(statements) = edge
            .get_mut("semantic")
            .and_then(|semantic| semantic.get_mut("statements"))
            .and_then(serde_json::Value::as_array_mut)
        {
            normalize_statement_defaults(statements);
        }
    }
    validate_retained_keys(&raw, &known)?;
    if selection.version != 1 {
        return Err("unsupported frozen selection version".into());
    }
    let members: std::collections::BTreeSet<_> = selection.members.iter().copied().collect();
    if members.len() != selection.members.len() || members.contains(&Uuid::nil()) {
        return Err("invalid frozen member references".into());
    }
    super::assertion_handles::validate_assertion_handles(
        selection
            .statements
            .iter()
            .map(|edge| (GraphStratum::Resource, edge)),
    )
    .map_err(|error| error.to_string())?;
    for edge in &selection.statements {
        let from = edge
            .from_node_id
            .parse::<Uuid>()
            .map_err(|_| "invalid frozen source id")?;
        let to = edge
            .to_node_id
            .parse::<Uuid>()
            .map_err(|_| "invalid frozen target id")?;
        if from.to_string() != edge.from_node_id
            || to.to_string() != edge.to_node_id
            || !members.contains(&from)
            || !members.contains(&to)
        {
            return Err("frozen statement endpoints must be member references".into());
        }
        if edge.assertions.is_some() && edge.has_legacy_assertion_data() {
            return Err("frozen relation mixes canonical and legacy assertion data".into());
        }
        if edge.assertions.is_none() {
            if let Some(semantic) = &edge.semantic
                && semantic.statements.is_empty()
                && (!semantic.sub_kinds.is_empty() || semantic.predicate.is_some())
            {
                return Err("frozen semantic statements require exact handles".into());
            }
        }
        // Reject malformed family/payload combinations instead of normalizing away data.
        let payload = super::snapshot::payload_from_persisted(edge);
        if super::snapshot::persisted_edge_for_ids(from, to, &payload) != *edge {
            return Err("inconsistent frozen relation payload".into());
        }
    }
    Ok(Some(selection))
}

impl Graph {
    /// Mint a Resource that bears a revision-frozen nested graph of references and
    /// exact relation copies. Member payloads stay in their owning resources.
    /// The spec is opaque to the kernel; the facade supplies its portable value.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn freeze_resource_selection(
        &mut self,
        spec: serde_json::Value,
        members: Vec<Uuid>,
    ) -> Result<Uuid, String> {
        self.freeze_resource_selection_with_nonce(spec, members, Uuid::new_v4())
    }

    /// Portable freeze entry point: the host supplies a fresh UUID nonce, as it
    /// does for new Surfaces on wasm. A reused address is refused before writing.
    pub fn freeze_resource_selection_with_nonce(
        &mut self,
        spec: serde_json::Value,
        mut members: Vec<Uuid>,
        nonce: Uuid,
    ) -> Result<Uuid, String> {
        members.sort();
        members.dedup();
        if members.iter().any(|id| self.resource(*id).is_none()) {
            return Err("missing frozen member resource".into());
        }
        let set: std::collections::BTreeSet<_> = members.iter().copied().collect();
        let statements = self
            .resource_edges()
            .filter(|(from, to, _)| set.contains(&from.id()) && set.contains(&to.id()))
            .map(|(from, to, payload)| {
                super::snapshot::persisted_edge_for_ids(from.id(), to.id(), payload)
            })
            .collect();
        let selection = FrozenSelection {
            version: 1,
            spec,
            revision: self.revision(),
            members,
            statements,
        };
        // A fresh address gives this record its own deterministic Resource identity.
        if nonce.is_nil() {
            return Err("frozen Resource nonce must be fresh".into());
        }
        let iri = format!("urn:uuid:{nonce}");
        let resource = super::ResourceNode::for_term(&iri);
        let record = crate::persistence::PersistedResourceRecord {
            canonical_iri: iri,
            facets: vec![crate::persistence::PersistedResourceFacet {
                facet: FROZEN_SELECTION.into(),
                value_json: serde_json::to_string(&selection).map_err(|e| e.to_string())?,
            }],
        };
        selection_from_record(&record)?;
        if self.resource(resource.id()).is_some()
            || !self.set_resource_record(resource.id(), Some(record.clone()))
        {
            return Err("frozen Resource admission refused".into());
        }
        self.record_delta(&super::CapturedDelta::ReplaySetResourceRecordById {
            resource_id: resource.id().to_string(),
            record: Some(record),
        });
        Ok(resource.id())
    }

    /// Open the immutable graph without loading or inventing its referenced members.
    pub fn open_frozen_selection(&self, owner: Uuid) -> Result<OpenedFrozenSelection<'_>, String> {
        let selection = self
            .resource(owner)
            .and_then(|resource| resource.nested_selection())
            .ok_or("resource bears no frozen selection")?;
        Ok(OpenedFrozenSelection {
            selection,
            coverage: self.coverage_for_resource_refs(selection.members()),
        })
    }
}

#[cfg(test)]
mod canonical_record_tests {
    use super::*;
    use crate::persistence::{
        PersistedEdge, PersistedResourceFacet, PersistedResourceRecord, PersistedSemanticStatement,
    };
    use crate::types::{AssertionBasis, GraphScope};

    fn assertion_edge(from: Uuid, to: Uuid, id: &str) -> PersistedEdge {
        PersistedEdge {
            from_node_id: from.to_string(),
            to_node_id: to.to_string(),
            families: vec![crate::persistence::PersistedEdgeFamily::Semantic],
            semantic: None,
            traversal: None,
            containment: None,
            arrangement: None,
            imported: None,
            provenance: None,
            assertions: Some(vec![PersistedSemanticStatement {
                statement_id: id.into(),
                predicate: "urn:test:claim".into(),
                recognized_sub_kind: None,
                label: Some("claim".into()),
                graph_scope: GraphScope::User,
                provenance_iri: Some("urn:test:author".into()),
                asserted_at_ms: Some(12),
                first_asserted_ms: Some(10),
                withdrawn: None,
                basis: AssertionBasis {
                    note: Some("basis note".into()),
                    ..Default::default()
                },
            }]),
        }
    }

    fn record(statements: Vec<PersistedEdge>) -> PersistedResourceRecord {
        let members = (1..=3).map(Uuid::from_u128).collect();
        let selection = FrozenSelection {
            version: 1,
            spec: serde_json::json!({}),
            revision: 1,
            members,
            statements,
        };
        PersistedResourceRecord {
            canonical_iri: "urn:uuid:selection".into(),
            facets: vec![PersistedResourceFacet {
                facet: FROZEN_SELECTION.into(),
                value_json: serde_json::to_string(&selection).unwrap(),
            }],
        }
    }

    #[test]
    fn frozen_selection_rejects_conflicting_canonical_ids_across_pairs() {
        let (first, second, third) = (Uuid::from_u128(1), Uuid::from_u128(2), Uuid::from_u128(3));
        let error = selection_from_record(&record(vec![
            assertion_edge(first, second, "same-id"),
            assertion_edge(first, third, "same-id"),
        ]))
        .unwrap_err();
        assert!(error.contains("one handle means one row"), "{error}");
    }

    #[test]
    fn frozen_selection_rejects_identical_copies_on_parallel_rows() {
        let row = assertion_edge(Uuid::from_u128(1), Uuid::from_u128(2), "copied");
        assert!(selection_from_record(&record(vec![row.clone()])).is_ok());
        let error = selection_from_record(&record(vec![row.clone(), row])).unwrap_err();
        assert!(error.contains("one handle means one row"), "{error}");
    }
}