OBEE-6 Document type for (tabular) instances

packages/backend/tests/user_state_tests.rs

@@ -50,7 +50,7 @@ mod integration_tests {
     }
 
     /// Creates document content for a child document (diagram) that links to a parent ref.
-    fn create_child_document_content(name: &str, parent_ref_id: Uuid) -> serde_json::Value {
+    fn create_child_diagram_document_content(name: &str, parent_ref_id: Uuid) -> serde_json::Value {
         json!({
             "version": "1",
             "type": "diagram",
@@ -68,6 +68,25 @@ mod integration_tests {
         })
     }
 
+    /// Creates document content for a child document (instance) that links to a parent ref.
+    fn create_child_instance_document_content(
+        name: &str,
+        parent_ref_id: Uuid,
+    ) -> serde_json::Value {
+        json!({
+            "version": "2",
+            "type": "instance",
+            "name": name,
+            "instanceOf": {
+                "_id": parent_ref_id.to_string(),
+                "_version": null,
+                "_server": "test",
+                "type": "instance-of"
+            },
+            "tables": {}
+        })
+    }
+
     // -----------------------------------------------------------------------
     // Document creation
     // -----------------------------------------------------------------------
@@ -411,14 +430,25 @@ mod integration_tests {
         assert_eq!(doc.theory.as_deref(), Some("causal-loop"));
 
         // Diagram (no theory)
-        let diagram_content = create_child_document_content("Test Diagram", ref_id);
-        let diagram_id =
-            document::new_ref(ctx, diagram_content).await.expect("Failed to create diagram");
+        let diagram_content = create_child_diagram_document_content("Test Diagram", ref_id);
+        let diagram_id = document::new_ref(ctx.clone(), diagram_content)
+            .await
+            .expect("Failed to create diagram");
 
         let s = read_user_state_from_samod(&state, &user_id).await.unwrap();
         assert_eq!(s.documents[&diagram_id.to_string()].type_name, DocumentType::Diagram);
         assert_eq!(s.documents[&diagram_id.to_string()].theory, None);
 
+        // Instance (no theory)
+        let instance_content = create_child_instance_document_content("Test Instance", ref_id);
+        let instance_id = document::new_ref(ctx, instance_content)
+            .await
+            .expect("Failed to create instance");
+
+        let s = read_user_state_from_samod(&state, &user_id).await.unwrap();
+        assert_eq!(s.documents[&instance_id.to_string()].type_name, DocumentType::Instance);
+        assert_eq!(s.documents[&instance_id.to_string()].theory, None);
+
         // Update theory and propagate user state
         let updated = create_model_document_content("Theory Test", "petri-net");
         let fake_heads: Vec<Vec<u8>> = vec![vec![0u8; 32]];
@@ -689,27 +719,42 @@ mod integration_tests {
         let parent_id = document::new_ref(ctx.clone(), create_test_document_content("Parent Doc"))
             .await
             .unwrap();
-        let child_id =
-            document::new_ref(ctx, create_child_document_content("Child Doc", parent_id))
-                .await
-                .unwrap();
+        let child_diagram_id = document::new_ref(
+            ctx.clone(),
+            create_child_diagram_document_content("Child Diagram", parent_id),
+        )
+        .await
+        .unwrap();
+        let child_instance_id = document::new_ref(
+            ctx,
+            create_child_instance_document_content("Child Instance", parent_id),
+        )
+        .await
+        .unwrap();
 
         get_or_create_user_state_doc(&state, &user_id).await.unwrap();
 
         let us = read_user_state_from_samod(&state, &user_id).await.unwrap();
-        assert_eq!(us.documents.len(), 2);
+        assert_eq!(us.documents.len(), 3);
 
         let parent = &us.documents[&parent_id.to_string()];
-        let child = &us.documents[&child_id.to_string()];
+        let child_diagram = &us.documents[&child_diagram_id.to_string()];
+        let child_instance = &us.documents[&child_instance_id.to_string()];
 
         assert!(parent.depends_on.is_empty());
-        assert_eq!(child.depends_on.len(), 1);
-        assert_eq!(child.depends_on[0].ref_id, parent_id);
-        assert_eq!(child.depends_on[0].relation_type, "diagram-in");
-
-        assert_eq!(parent.used_by.len(), 1);
-        assert_eq!(parent.used_by[0].ref_id, child_id);
-        assert!(child.used_by.is_empty());
+        assert_eq!(child_diagram.depends_on.len(), 1);
+        assert_eq!(child_diagram.depends_on[0].ref_id, parent_id);
+        assert_eq!(child_diagram.depends_on[0].relation_type, "diagram-in");
+        assert_eq!(child_instance.depends_on.len(), 1);
+        assert_eq!(child_instance.depends_on[0].ref_id, parent_id);
+        assert_eq!(child_instance.depends_on[0].relation_type, "instance-of");
+
+        assert_eq!(parent.used_by.len(), 2);
+        let used_by_ref_ids: Vec<_> = parent.used_by.iter().map(|doc| doc.ref_id).collect();
+        assert!(used_by_ref_ids.contains(&child_diagram_id));
+        assert!(used_by_ref_ids.contains(&child_instance_id));
+        assert!(child_diagram.used_by.is_empty());
+        assert!(child_instance.used_by.is_empty());
 
         Ok(())
     }
@@ -736,23 +781,37 @@ mod integration_tests {
         let parent_id = document::new_ref(ctx.clone(), create_test_document_content("Parent Doc"))
             .await
             .unwrap();
-        let child_id =
-            document::new_ref(ctx, create_child_document_content("Child Doc", parent_id))
-                .await
-                .unwrap();
+        let child_diagram_id = document::new_ref(
+            ctx.clone(),
+            create_child_diagram_document_content("Child Diagram", parent_id),
+        )
+        .await
+        .unwrap();
+        let child_instance_id = document::new_ref(
+            ctx,
+            create_child_instance_document_content("Child Instance", parent_id),
+        )
+        .await
+        .unwrap();
 
         let us = read_user_state_from_samod(&state, &user_id).await.unwrap();
-        assert_eq!(us.documents.len(), 2);
+        assert_eq!(us.documents.len(), 3);
 
         let parent = &us.documents[&parent_id.to_string()];
-        let child = &us.documents[&child_id.to_string()];
+        let child_diagram = &us.documents[&child_diagram_id.to_string()];
+        let child_instance = &us.documents[&child_instance_id.to_string()];
 
         assert!(parent.depends_on.is_empty());
-        assert_eq!(child.depends_on.len(), 1);
-        assert_eq!(child.depends_on[0].ref_id, parent_id);
-        assert_eq!(parent.used_by.len(), 1);
-        assert_eq!(parent.used_by[0].ref_id, child_id);
-        assert!(child.used_by.is_empty());
+        assert_eq!(child_diagram.depends_on.len(), 1);
+        assert_eq!(child_diagram.depends_on[0].ref_id, parent_id);
+        assert_eq!(child_instance.depends_on.len(), 1);
+        assert_eq!(child_instance.depends_on[0].ref_id, parent_id);
+        assert_eq!(parent.used_by.len(), 2);
+        let used_by_ref_ids: Vec<_> = parent.used_by.iter().map(|doc| doc.ref_id).collect();
+        assert!(used_by_ref_ids.contains(&child_diagram_id));
+        assert!(used_by_ref_ids.contains(&child_instance_id));
+        assert!(child_diagram.used_by.is_empty());
+        assert!(child_instance.used_by.is_empty());
 
         Ok(())
     }

packages/document-methods/src/index.ts

@@ -1,9 +1,11 @@
 export type { DiagramDocument } from "./diagram";
+export type { InstanceDocument } from "./instance";
 export type { LLMConversationDocument } from "./llm_conversation";
 export type { ModelDocument } from "./model";
 export type { FormalCell, RichTextCell } from "./notebook";
 
 export * as Diagram from "./diagram";
 export * as LLMConversation from "./llm_conversation";
+export * as Instance from "./instance";
 export * as Model from "./model";
 export * as Nb from "./notebook";

packages/document-methods/src/instance.ts

@@ -0,0 +1,17 @@
+import type { Document, StableRef } from "catcolab-document-types";
+import { currentVersion } from "catcolab-document-types";
+
+/** A document defining a instance in a model. */
+export type InstanceDocument = Document & { type: "instance" };
+
+/** Create an empty instance of a model. */
+export const newInstanceDocument = (modelRef: StableRef): InstanceDocument => ({
+    name: "",
+    type: "instance",
+    instanceOf: {
+        ...modelRef,
+        type: "instance-of",
+    },
+    tables: {},
+    version: currentVersion(),
+});

packages/document-types/src/v0/api.rs

@@ -57,6 +57,9 @@ pub enum LinkType {
     #[serde(rename = "diagram-in")]
     DiagramIn,
 
+    #[serde(rename = "instance-of")]
+    InstanceOf,
+
     #[serde(rename = "llmconversation-of")]
     ConversationOf,
 

packages/document-types/src/v2/cell.rs

@@ -13,12 +13,19 @@ use crate::v1;
 #[serde(tag = "tag")]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub enum NotebookCell<T> {
+    /// A rich-text cell.
     #[serde(rename = "rich-text")]
     RichText { id: Uuid, content: RichTextContent },
     #[serde(rename = "formal")]
-    Formal { id: Uuid, content: T },
+    Formal {
+        /// The ID of the cell.
+        id: Uuid,
+        /// The formal content of the cell.
+        content: T,
+    },
 }
 
+/// Short-hand declaration for readability.
 #[declare]
 pub type Cell<T> = NotebookCell<T>;
 

packages/document-types/src/v2/document.rs

@@ -1,6 +1,7 @@
+use crate::current::instance::Table;
 use crate::v0::AnalysisType;
 use crate::v1;
-pub use crate::v1::DocumentType;
+use std::{collections::HashMap, str::FromStr};
 
 use super::analysis::Analysis;
 use super::api::Link;
@@ -9,6 +10,7 @@ use super::notebook::Notebook;
 
 use serde::{Deserialize, Serialize};
 use tsify::Tsify;
+use uuid::Uuid;
 
 /// This is the content of a model document. For legacy reasons, we reserve
 /// the name "ModelDocument" for `Document & { type: "model" }`.
@@ -37,6 +39,16 @@ pub struct DiagramDocumentContent {
     pub version: String,
 }
 
+#[derive(PartialEq, Debug, Serialize, Deserialize, Tsify)]
+#[tsify(into_wasm_abi, from_wasm_abi, hashmap_as_object)]
+pub struct InstanceDocumentContent {
+    pub name: String,
+    #[serde(rename = "instanceOf")]
+    pub instance_of: Link,
+    pub tables: HashMap<Uuid, Table>,
+    pub version: String,
+}
+
 #[derive(PartialEq, Eq, Debug, Serialize, Deserialize, Tsify)]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub struct AnalysisDocumentContent {
@@ -49,7 +61,7 @@ pub struct AnalysisDocumentContent {
     pub version: String,
 }
 
-#[derive(PartialEq, Eq, Debug, Serialize, Deserialize, Tsify)]
+#[derive(PartialEq, Debug, Serialize, Deserialize, Tsify)]
 #[serde(tag = "type")]
 #[tsify(into_wasm_abi, from_wasm_abi)]
 pub enum Document {
@@ -59,10 +71,52 @@ pub enum Document {
     Diagram(DiagramDocumentContent),
     #[serde(rename = "analysis")]
     Analysis(AnalysisDocumentContent),
+    #[serde(rename = "instance")]
+    Instance(InstanceDocumentContent),
     #[serde(rename = "llmconversation")]
     LLMConversation(LLMConversationDocumentContent),
 }
 
+/// The type/kind of a document, without any associated content.
+#[derive(PartialEq, Eq, Debug, Clone, Copy, Serialize, Deserialize, Tsify)]
+#[cfg_attr(
+    feature = "backend",
+    derive(autosurgeon::Reconcile, autosurgeon::Hydrate, ts_rs::TS)
+)]
+#[cfg_attr(
+    feature = "backend",
+    ts(export_to = "user_state.ts", rename_all = "lowercase")
+)]
+#[serde(rename_all = "lowercase")]
+#[tsify(into_wasm_abi, from_wasm_abi)]
+pub enum DocumentType {
+    #[cfg_attr(feature = "backend", autosurgeon(rename = "model"))]
+    Model,
+    #[cfg_attr(feature = "backend", autosurgeon(rename = "diagram"))]
+    Diagram,
+    #[cfg_attr(feature = "backend", autosurgeon(rename = "instance"))]
+    Instance,
+    #[cfg_attr(feature = "backend", autosurgeon(rename = "analysis"))]
+    Analysis,
+    #[cfg_attr(feature = "backend", autosurgeon(rename = "llmconversation"))]
+    LLMConversation,
+}
+
+impl FromStr for DocumentType {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "model" => Ok(DocumentType::Model),
+            "diagram" => Ok(DocumentType::Diagram),
+            "instance" => Ok(DocumentType::Instance),
+            "analysis" => Ok(DocumentType::Analysis),
+            "llmconversation" => Ok(DocumentType::LLMConversation),
+            other => Err(format!("unknown document type: {other}")),
+        }
+    }
+}
+
 impl Document {
     pub fn migrate_from_v1(old: v1::Document) -> Self {
         match old {

packages/document-types/src/v2/instance.rs

@@ -0,0 +1,43 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use tsify::Tsify;
+use uuid::Uuid;
+
+/// The value of a single "cell" (i.e. field) in a table row. If the column corresponds to an
+/// attribute morphism then we provide the value of the type; if the column corresponds to a
+/// mapping morphism then we provide the uuid of the row.
+#[derive(PartialEq, Debug, Serialize, Deserialize, Tsify)]
+pub enum FieldValue {
+    /// Base type: the empty type.
+    Null,
+    /// Base type: boolean.
+    Bool(bool),
+    /// Base type: integer.
+    Int(i32),
+    /// Base type: float.
+    Float(f32),
+    /// Base type: string.
+    String(String),
+    /// Mapping type: the uuid of another row.
+    RowRef(Uuid),
+}
+
+/// A single row of a table.
+#[derive(PartialEq, Debug, Serialize, Deserialize, Tsify)]
+pub struct TableRow {
+    /// The row "number".
+    pub id: Uuid,
+    /// The content of the row, given as a map from column IDs to values.
+    pub fields: HashMap<Uuid, FieldValue>,
+}
+
+/// A single table, corresponding to a single entity.
+#[derive(PartialEq, Debug, Serialize, Deserialize, Tsify)]
+pub struct Table {
+    /// The uuid of the entity to which this table corresponds.
+    pub id: Uuid,
+    /// The rows of the table.
+    pub rows: HashMap<Uuid, TableRow>,
+    /// The order of the rows of the table.
+    pub row_order: Vec<Uuid>,
+}

packages/document-types/src/v2/mod.rs

@@ -2,9 +2,14 @@ use crate::v1;
 
 pub use v1::{analysis, api, diagram_judgment, model, model_judgment, path, theory};
 
+/// Cells in a notebook.
 pub mod cell;
+/// Model documents, containing a notebook along with metadata.
 pub mod document;
+/// Tabular instances of models.
+pub mod instance;
 pub mod llm_conversation;
+/// Notebooks for models and diagrams.
 pub mod notebook;
 pub mod rich_text;
 

packages/frontend/src/page/document_breadcrumbs.tsx

@@ -39,6 +39,8 @@ export function getParentRefId(document: Document): string | null {
             return null;
         case "diagram":
             return document.diagramIn._id;
+        case "instance":
+            return document.instanceOf._id;
         case "analysis":
             return document.analysisOf._id;
         case "llmconversation":